Service Identification [v?.?.?]

for Broadcasters & Aggregators

Please note that, because of the style sheet features of this document, the browser you are currently using will not be able to fully render the document. In practice this means that you will find section numbering may not appear and the document won't print properly. Please use Firefox 3.5+

If you wish to print this document from your browser, please make sure you are using Firefox 3.5+. However, we do make available a PDF copy of the specifications for you to download.

Executive Summary

The IMDA publishes their Service Identification for Broadcasters & Aggregators in an attempt to standardise the industry of Internet Radio, in the first instance, and establish a working framework for future media services.

The Service Identification describes a way for a broadcaster, or media organisation, to expose their data to a hardware or software solution run by a third party. The data from the media organisation contains details of itself, its brands and its brands' transport methods.

Not only is this technical information but also editorial information allowing the solution to correctly categorise and expose brands to the audience, and to allow a solution to evaluate appropriateness of brands to criteria supplied where the solution includes some search functionality or automated browsing features.

In order for an organisation to make available this data to others the IMDA recommends the organisation to follow the Service Identification specifications included in this document so that common understanding, ease of repurposing and avoidance of publishing data in different formats for different solutions is achieved. This provides benefits for both the media organisation and the solution provider.

Table of Contents

Appendices

Introduction

Before we go further – it is important to understand some basic terminology we use as this is often a point of confusion:

solution

we believe that a device exists, in the majority, connected to a server run by the manufacturer of the device or the aggregator that controls the device – often it is easier to refer to this as a 'solution' which is the combination of the device and the server that powers it. Consider the 'solution' a black-box which you cannot, and do not need to, see inside.

media organisation

we identify the broadcaster, publisher or individual that has media services as a 'media organisation' for simplicity. (e.g. BBC, Soma FM, Clear Channel, CNN, etc)

brand

in order to identify a service (e.g. BBC Radio 4, Groove Salad, ITV1, etc) we refer to an individual service as a 'brand' which a media organisation has one or more of.

transport

each brand may have multiple ways of distributing the content via Internet Protocol - we identify these as a 'transport'. (e.g. via Windows Media streaming, Shoutcast streaming, Flash streaming, etc)

These documents describe a way for a media organisation to expose their data to a solution (or solutions). This data regards details of itself, its brands and its brands' transport methods.

Not only is this technical information but also editorial information allowing the solution to correctly categorise and expose brands to the audience, and to allow a solution to evaluate appropriateness of brands to criteria supplied where the solution includes some search functionality or automated browsing features.

In order for an organisation to make available this data to others the IMDA recommends the organisation to follow the specification included in this document so that common understanding, ease of repurposing and avoidance of publishing data in different formats for different solutions is achieved. This provides benefits for both the media organisation and the solution provider.

The IMDA specification defines a number of XML documents and the Schema for these documents that a media organisation can use to expose their data.

Licence

The IMDA is publishing this specification under the GNU General Public License version 3 and the GNU Free Documentation License version 1.3. We feel that it is important that access to this is not limited, and allows any media organisation to make use of it. We have made every effort not to include references to other types of licensed specifications – where this simply hasn't been possible we clearly sign post areas which you need to pay special attention to.

"IMDA Service Identification for Broadcasters & Aggregators"

- GNU General Public License version 3 -

Copyright (C) 2010 Internet Media Device Alliance

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/. For questions please contact the Internet Media Device Alliance (IMDA) Program Manager at +1 631 261 5536 or send an email to info@imdalliance.org

- GNU Free Documentation License version 1.3 -

Copyright (C) 2010 Internet Media Device Alliance

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the full license is available at the following location: http://www.gnu.org/copyleft/fdl.html

How this document is structured

Each section will give you an overview of the specification by using a simple block diagram, then the section will go into detail of the data types and values required to correctly build your XML document(s).

When defining these data types and values we have provided examples where necessary to identify best practice. If there is information specific to a media organisation or the solution provider then we will show this as follows:

This 'call out' highlights specific information that the media organisation or broadcaster may find useful.

This 'call out' highlights specific information that the solution provider or aggregator may find useful.

With our specifications there is much which is optional. We will attempt to identify which areas must be completed by the visual 'black triangle' in our box diagrams (see below for an example) which we use to provide an initial overview of a section and by highlighting a summary of what is required on each section (in a box to the right of a section's title). This is the 'minimum metadata set'. We will also use the 'call outs' above to advise you about areas which may not be required but to advise you of reasons why you may wish to complete the information for best practice. There are many example XML documents used throughout this specification, and we have grouped the main example documents together in Appendix B – we have also made available there copies of the main documents cut down to the minimum they need, but urge you to read the specification as we give guidance on why you should use optional nodes and attributes to give more information which may result in your brands being easier to find.

We also use a shorthand to refer to a particular node or attribute and its parentage. This 'shorthand' is actually XPath – a syntax for defining parts of an XML document. Although a good introduction to XPath is available from W3Schools, a quick check here may help. In this very simple example we have an XML fragment that is:

Then if we wanted to identify the 'nickname' attribute we would write:

name/firstname@nickname

Which simply means that firstname is a child of name – the order reads left to right and this identifies the parentage of children, we separate nodes by a '/' (slash). The @nickname is an attribute and we identify attributes with an '@' (at symbol). This allows you to see what area of an XML document we are referring to.

We have tried to provide examples of xml which can be understood by most, to have some shared understanding, so we have used some of the BBC's brands and details – though the BBC is a founding member of the IMDA, it should be noted that the examples contained here are fictitious and are for explanation only. The BBC's real IMDA Service Identification is very different.

General advice

Why UTF-8?

The IMDA Service Identification define a set of files that are all XML. All your xml should open with the XML declaration which identifies the character set we will be using: UTF-8. Reasons for picking UTF-8 are covered in excellent article from IBM.

Are there XML schemas available?

Yes, a set of XML schemas are available on our website – these can be used to validate your content. All full list of all schemas is available in the Appendices (see Appendix "XML Schemas")

Is there a Data Relationship Diagram available?

In a future version of these specifications we will include a data relationship diagram (probably in the Appendix). We have a working diagram used to help us understand the relations between data entities (objects) described here. We are currently considering including this as some may find it useful where it gives an overview of relations and can be helpful in understanding the structure of the XML file. It may also prove useful as a guideline when implementing a database (e.g. for the aggregator). If you are interested, please provide feedback to us.

Why split data into multiple XML documents?

As you will discover, our specification identifies multiple XML files that should be created. Why? Surely we could have put everything into one XML document?

There are few reasons for splitting things up – it's mainly about making things more manageable and also thinking to how others will pick up this data in an Internet Protocol world. It's also about the future.

Although we have provided the initial split up we are allowing XML Inclusions (XInclude) in the sub-documents, but not in the root document.

Here's a few reasons why we have split things up:

• By grouping data into separate XML documents, where similar data may come from different areas in an media organisation's – we've tried to group data together so that they could be managed by different teams. Indeed – you can make use of XInclude in the sub-documents should there be further need to split things up.
• Not everything updates as regularly as everything else – so information about the media organisation may not change very much for long periods, whereas services of the media organisation may change occasionally. In the future we will include being able to expose Electronic Programme Guides and On-Demand services – this changes far more frequently. Combine this with the 'weight' (file size) of the documents – heavy documents that frequently change need to be accessed by solutions very often to keep things up to date. Keeping things grouped into as small a file size as possible, without having any extraneous information, can be desirable.
• Changing specifications – because the IMDA Service Identification will be a live, ever changing, set of specifications we need to consider how changes will be rolled out and the scope of the impact on existing organisations using them. By also keeping stuff in separate documents we should be able to minimise the impact, the dependencies.

Important: as an aggregator you must make sure you check for a resolve XInclude directives as per the XML Inclusions standard from the W3C as an organisation may have used these in sub-documents (Organisation, Brands, Transports...)

Why don't we allow XInclude within the root document? You might wonder why the root document contains references to external sub-documents (organisation, brands, transports, ...) rather than allowing XInclude's to insert the content of those into the root document. There was much discussion about this but, in the end, one of the reasons why we decided to restrict the use of XInclude to sub-documents was because you would require one schema document to validate the entire document (where XInclude results in including everything into the root node somehow). This would make the schema potentially unwieldy, not to mention requiring solutions to read the root document and pull in all the XInclude external references every time. It just wasn't a good idea.

Are there any requirements for the web server that the files reside on?

It is important that an organisation comply with the following requirements, this is mainly to help the solutions that may be requesting data:

• Web Server should comply to HTTP/1.1 – this is a recommendation to allow organisations to use the new cache features that 1.1 brought, including headers like If-modified-since which could allow an aggregator/solution to be more efficient.
• Atomic updates! As an organisation you should avoid putting partial files onto your server, even if you have a backend system that creates any of the documents you should create them elsewhere and then overwrite the old files with them – this is to lessen the likelihood that a solution would request data and receive unfinished content.
• Don't leave old files lying around on your web server – because our spec allows you to put sub-documents into any location you please it is important that, should you move any of those documents, you delete the old file. A request for the old document location should result in an HTTP 404 error begin returned – if a solution receives a 404, then they should restart the parsing of an organisation's IMDA Service Identification documents at the root document - imda.xml

How should a solution determine if a file has been updated?

We cannot prescribe the method a solution would use, however here are some recommendations:

• an organisation's web server may return the modified date of the file on the file system – it would be sensible to make sure the modified date doesn't keep changing when the file itself doesn't, this may be because you have some script running on your web server.
• an organisation can suggest the modified date also in the document itself (this is an attribute in the root node of each document, as you will see). This modified date should only be updated if you update the file. Also – the modified date of a sub-document shouldn't be 'bubbled' upwards to the root document, the modified date attribute is about the document it is defined in and not anything else.

How to provide feedback and input to specifications

We are keen to hear your feedback on these specifications. Whether it's a specific problem or an improvement idea please – get in touch with us by email. There are also specific areas in the specification where we maintain a list of possible values for particular attributes – we point these out in the documentation and feedback via our email is requested if the values don't fit your needs.

You should be aware that this specification may change over time as we add new services, so we have made sure the version of this specification is available at the top of the document. We have made every effort to make sure we don't make significant structural changes to existing specifications – however, we cannot guarantee that future changes won't require structural changes. In the near future we will add a notification system that you can subscribe to in order to make sure you are kept up to date with any changes.

Another resource is our Frequently Asked Questions regarding this specification document – you can find these in the Appendix: Frequently Asked Questions. You may want to check this before getting in touch.

Our website is: www.imdalliance.org

Email your feedback regarding the specifications: metadata@imdalliance.org

Service Identification

In order for media organisations to expose the availability of their IP services we ask the media organisation to publish several XML files publicly available on their web servers. The first of which allows easy discovery of services and is called imda.xml and an example of where this would be located is:

http://www.organisation.com/imda.xml

The imda.xml file is an organisation's entry point to all service related metadata that follows the IMDA specifications. The file is relatively short and merely acts like a sitemap of service.

Having your metadata organized in this standardised way is really useful. However being able to provide metadata yields to the next question: How do I provide my XML-files or even just the change of one certain file to the solution provider? As, from a media organisations point of view, there are a lot of solution providers to address... and from a solution providers point of view there are even more media organisations.

That’s why the IMDA is currently also working on an optional service which works alongside this open specification, which will allow a simple and easy-to-use way of providing notifications around changes to your metadata via a central entity for the benefit of both organisations and solution providers alike. We call it the CDS – the Central Discovery Service. And it will be coming soon.

Let's take a look at the main elements of this file:

Reading from the top of this tree, we see that it contains information about:

Terms & Conditions

Presents the terms and conditions of use of this data. The IMDA has suggested a default wording here to allow most systems to immediately make use of your data. However if you specify any exceptions to those general terms it may delay or stop your listing in particular solutions.
This also includes the IMDA approved 'safe content' definition - referred to by 'brands'. It also includes the ability to specify a Privacy Policy.

Organisation

Contains information that describes the broadcaster or media organisation. Includes: title, description, logos, location, genres and other classification information.

Brands

Contains information that describes the brand/services/channels offered by the organisation : e.g. BBC Radio 4, Groove Salad, etc. Also contains information on logical groupings of brands.

Transports

Contains information that describes how to playback audio/video of a particular brand. e.g. the Windows Media simulcast stream details for the brand BBC Radio 4. In the future this may contain information about other transport types not just IP services.

Manifests

Contains information around schedule and programme data for brands. e.g. the schedule of programmes for BBC Radio 3, the podcast RSS for NPR podcasts.

As a quick example of how this could appear in the XML file, using the BBC as the media organisation:

Hopefully, from this simple example, there should be much that makes sense. You should see that it is fairly straightforward. We'll now look at the nodes and attributes in detail – our root node is imda.

imda node

node is requiredThe imda node encloses our service metadata but itself contains information in attributes about the last modified date and an email contact address for the owner of the data. Inside imda we will keep references to various files/services – these are currently information regarding the media organisation, the brands of the organisation and the transports for the brands.

imda@modified

attribute is requiredThis attribute contains a time stamp of when you last updated the file. The data type used here follows ISO 8601 recommendations, and we use 'Z' to denote the timezone 'Zulu Time' (UTC). Do not use a local timezone here for simplicity of comparison. Example – 27th of October 2009, at 15 hrs 5 minutes and 30 seconds Zulu would be:

2009-10-27T150530Z

imda@owner

attribute is requiredDefine an email address that can be used to contact the department/person looking after these files – this is to allow solution providers to contact them should there be a problem. We recommend you to use an alias here to allow you to route the email to the correct department/person rather than a real name here for privacy reasons. From the example:

imda.services@bbc.co.uk

imda@imdaversion

attribute is requiredIn order to assist solutions to make sure they are checking your document, based on compatibility with a particular version of these IMDA Service Identification specifications, an organisation should specify here the version number of these specs that they have used in this and all sub-documents. This is to make sure that, as an organisation providing the data, you can be sure that interpretation of the data you provide is based on the version of the specifications you used to create them. At the moment, this is for future use – should new versions be provided then solutions know what to expect: when checking for compatibility only the major and minor version should match, changes only made to the revision should have no influence on the implementation.

The version of this specification document is visible on the first page, at the top and is also printed at the foot of the document. The current version of this document is:

Our version number consists of three parts:

<major>.<minor>.<revision>

Rules for updating the major, minor and revision numbers:

• major – incremented by one if the specification is not upward compatible with the previous specification. This means that your implementation needs to be modified in order to be compliant with the specification. Incrementing the major version will reset the minor and revision version to zero. Examples of changes that will cause an update of the major version number:
  • If the hierarchy of existing nodes and/or attributes changes. This will be visible in a change of the XPath of an element.
  • Addition of new nodes and/or attributes which are required "to make it work" (e.g. because it was an omission in a previous specification)
• minor – incremented by one if the specification is upward compatible with the previous specification but your implementation needs to be modified in order to be compliant with the specification. Incrementing the minor version will reset the revision version to zero. The major version number will not be affected. Examples of changes that will cause an update of the minor version number:
  • addition of nodes and/or attributes which are not required "to make it work" but offer new or extended (optional) functionality which was not present in the previous specification.
  • Changes in the semantics of existing nodes and/or attributes which may include:
    • changes in the interpretation of attribute values
    • changes in the name (not hierarchy) of a node and/or attribute
• revision – incremented by one if the specification is upward compatible with the previous specification. Your implementation does not have to be modified in order to be compliant with the specification. Incrementing the revision version will not affect the major and minor version. Examples of changes that will cause an update of the revision number:
  • changes in text which have no influence on the functionality. This will mainly be applicable to non-functional requirements such as legal issues.

imda/terms

node is requiredThe terms node contains definitions used by the organisation to set out the terms of use for their content (metadata, logos, media... ) and allow an organisation to make a declaration about the suitability of their content. This is to allow any solution provider to find this out easily. The general terms and conditions are defined in the terms/general node and if you have any specific exceptions to these, we recommend you list these in terms/exception node.

imda/terms/general

node is required, @url is requiredThe general terms and conditions of use for the organisation's content is presented here. This should cover any content available in this or other linked resources. This is a required node.

The general node contains a url attribute which should be an absolute URL to a plain text file that contains your full terms and conditions. The IMDA provides a default set of terms and conditions which is available here, and you can use as the value of the url attribute:

http://www.imdalliance.org/metadata/docs/termsV1.txt

Best practice guidance: you can use terms and conditions provided by your organisation – however you should really consider following the default terms and conditions provided by the IMDA. These have been created to allow a solution provider to see quickly that your terms and conditions are a previously agreed set from the IMDA. If you provide your own terms and conditions then a solution provider will have to review your content manually – this may delay or disqualify you entirely from that solution provider. You should seriously consider being able to accept the default IMDA terms and conditions.

Because the default terms and conditions the IMDA provides is stored on our own servers at the URL above, for a solution it is simple to check to see if the organisation is using them – just look for the URL above.

imda/terms/exceptions

node is optional, @url only required if node is providedA textual description of any restrictions or exceptions you may have to your general terms and conditions defined in terms/general. This is an optional node.

If you have no exceptions, do not include an exceptions node.

If you do, then the exceptions node contains a url attribute which should be an absolute URL to a plain text file that contains details of these exceptions.

Best practice guidance: if you have used the default IMDA terms and conditions in terms/general then you should have no exceptions – and therefore no terms/exceptions node. If you do put exceptions in here then you should understand this will require review of your terms by the solution provider – this may delay or disqualify you entirely from that solution provider.

If terms/general is the default IMDA terms and conditions and terms/exceptions is empty then you can assume that the content of these files is within the default terms and conditions provided by the IMDA – in so far as the IMDA doesn't check all media organisations for compliance with these and cannot be held responsible for any misuse or liability resulting. The responsibility of checking this is between the media organisation and the solution provider.

imda/terms/privacy

node is required, @url is requiredThis node presents the privacy policy that a media organisation needs any third-party using their content to meet or exceed. This should cover any content available in this or other linked resources. This is a required node.

The privacy node contains a url attribute which should be an absolute URL to a plain text file that contains your full privacy policy. The IMDA provides a default privacy policy which is available here, and you can use as the value of the url attribute:

http://www.imdalliance.org/metadata/docs/privacyV1.txt

Best practice guidance: you can use a privacy policy provided by your organisation – however you should really consider following the default one provided by the IMDA. These have been created to allow a solution provider to see quickly that they can meet a known privacy policy level agreed previously with the IMDA. If you provide your own privacy policy then a solution provider will have to review your content manually – this may delay or disqualify you entirely from that solution provider. You should seriously consider being able to accept the default Privacy Policy provided by the IMDA.

Because the default Privacy Policy the IMDA provides is stored on our own servers at the URL above, for a solution it is simple to check to see if the organisation is using them – just look for the URL above.

imda/terms/privacyexceptions

node is optional, @url only required if node is providedA textual description of any restrictions or exceptions you may have to your privacy policy defined in terms/privacy. This is an optional node.

If you have no exceptions, do not include a privacyexceptions node.

If you do, then the privacyexceptions node contains a url attribute which should be an absolute URL to a plain text file that contains details of these exceptions.

Best practice guidance: if you accept the default Privacy Policy provided by the IMDA in terms/privacy then you should have no exceptions – and therefore no terms/privacyexceptions node. If you do put exceptions in here then you should understand this will require review of your terms by the solution provider – this may delay or disqualify you entirely from that solution provider.

If terms/privacy is the default Privacy Policy provided by the IMDA and terms/privacyexceptions is empty then you can assume that the content of these files is within the default Privacy Policy provided by the IMDA – in so far as the IMDA doesn't check all media organisations for compliance with these and cannot be held responsible for any misuse or liability resulting. The responsibility of checking this is between the media organisation and the solution provider.

imda/terms/safecontent

node is required, @url is requiredDefinition of what 'safe content' is in terms of the media organisation providing the enclosed data and services. This is used in other linked resources to identify brands/services as 'safe content'. This is a required node.

The safecontent node contains a url attribute which should be an absolute URL to a plain text file that contains your definition of safe content. The IMDA provides a default definition of safe content which is available here, and you can use this as the value for the url attribute:

http://www.imdalliance.org/metadata/docs/safeV1.txt

Best practice guidance: you can use the definition of 'safe content' provided by your organisation – however you should really consider following the default definition provided by the IMDA. This has been created to allow a solution provider to see quickly that your definition of 'safe content' is a previously agreed definition from the IMDA. If you provide your own definition, then a solution provider will have to review your content manually – this may delay or disqualify you entirely from that solution provider. You should seriously consider being able to accept the default IMDA definition.

Because the default 'safe content' definition that the IMDA provides is stored on our own servers at the URL above, for a solution it is simple to check to see if the organisation is using them – just look for the URL above.

imda/organisation

node is required, @url is required, @protect is optionalThis node contains information about the location of the XML file that describes the media organisation in greater detail. The @url attribute of this node contains an absolute URL to the location of your organisation xml file. The location may use http or https, and may be protected with HTTP basic authentication – please see 'Protecting your metadata' below. If your url describes a location protected in this manner then you should add the protect attribute with the value "true" to flag to the solution that they will need to provide authentication. The authentication information may be negotiated with the owner of the metadata by contacting the email address described in the imda@owner attribute.

imda/brands

node is required, @url is required, @protect is optionalThis node contains information about the location of the XML file that describes the brands of the media organisation. The url attribute of this node contains an absolute URL to the location of your brands xml file. The location may use http or https, and may be protected with HTTP basic authentication – please see 'Protecting your metadata below. If your url describes a location protected in this manner then you should add the protect attribute with the value "true" to flag to the solution that they will need to provide authentication. The authentication information may be negotiated with the owner of the metadata by contacting the email address described in the imda@owner attribute.

imda/transports

node is required, @url is required, @protect is optionalThis node contains information about the location of the XML file that describes the transport methods for the brands. The @url attribute of this node contains an absolute URL to the location of your transports xml file. The location may use http or https, and may be protected with HTTP basic authentication – please see 'Protecting your metadata' below. If your url describes a location protected in this manner then you should add the protect attribute with the value "true" to flag to the solution that they will need to provide authentication. The authentication information may be negotiated with the owner of the metadata by contacting the email address described in the imda@owner attribute.

imda/manifests

node is optional, if node is used then @url is required, @protect is optionalThis node contains information about the location of the XML file that describes manifests of data regarding particular brands – the data held might be schedule information regarding programming related to a particular brand, or the information required to find editorial details of podcast programming for a particular brand. The @url attribute of this node contains an absolute URL to the location of your manifests xml file. The location may use http or https, and may be protected with HTTP basic authentication – please see 'Protecting your metadata' below. If your url describes a location protected in this manner then you should add the protect attribute with the value "true" to flag to the solution that they will need to provide authentication. The authentication information may be negotiated with the owner of the metadata by contacting the email address described in the imda@owner attribute.

Why 'manifests'? It might sound like an unusual word choice but we wanted something that signified 'a list of things'. Manifests was suggested earlier on, with a number of other options in different languages - but we came back to 'manifests'. Consider the dictionary definition:

manifest [noun] ~ a document giving comprehensive details of a ship and its cargo and other contents, passengers, and crew for the use of customs officers. [verb, transitive] to record in such a manifest - e.g. every passenger is manifested at the point of departure.

In future releases of this specification the manifests document will be used for 'on-demand' services related to brands.

Protecting your metadata

The IMDA strongly recommends that you make all XML documents publicly available – allowing anyone to request the information. However, we understand that some organisations may require to protect some of their data for their own reasons – we ask that organisations always make the root imda document publicly available but that they can protect sub-documents using HTTP basic authentication, as noted in the above details.

If an organisations decides to protect a sub-document then they can use HTTPS to protect the data transferred and use HTTP basic authentication to allow or deny access to the location of the document. If you do this, please make sure that your imda@owner email address is valid and allows solutions to contact you about gaining access. The authentication information may be negotiated with the owner of the metadata by contacting the email address described in the imda@owner attribute.

Be aware that a solution may or may not automatically list the organisation's services should you protect your data in this way as the solution will need to contact you and seek agreement on use. This allowance has been provided for organisations who wish to control who has access to their metadata.

Organisation Identification

In order to provide information to a solution about the organisation's identification we provide information in a file referenced from the imda.xml root file in imda/organisation@url. As we said, we don't mind what this file is called or where it is located – as long as it's publicly available. As an example – our organisation identification file could be here:

http://imda.organisation.com/imda_org.xml

The contents of this file allow an organisation to describe both data that is used visually by a solution to identify the organisation to a consumer, as well as data that is used purely to create links to show ownership of the services identified in other IMDA specifications.

Let's take a look at the main elements of this file:

Reading from the top of this tree, we see that it contains information about:

Title

Title of organisation - in multiple lengths (short, medium, long and extended) and with multiple language support.

Description

Description of organisation - in multiple lengths (short, long and extended) and with multiple language support.

Links

Allows organisation to associate urls for further information about themselves. e.g. organisation's home page on the web, or their mobile service.

Tags

Allows organisation to provide free-form tagging and key wording. Each tag may signal its weighting to other tags provided, and future extensions may allow categorisation.

Genres

Categorise the organisation by Genre (if appropriate).

Logos

Publish logos that solutions can use to represent this organisation.

Headquarters

The location of the organisation's head office of a location id (see Locations)

Locations

Allows an organisation to define various geographical data to be used in this or other files: latitude/longitude points, lat/long polygons or countries.

Here is a quick example of how this could appear in the XML file, again we're using the BBC as the media organisation in this example:

In the above example we've tried to keep things simple, to show some of the ways of describing the data. However – the details begin with our root node for this document: organisation.

organisation node

node is requiredThe organisation node encloses all our metadata that describes our media organisation. This root node contains information in attributes about the last modified date and an email contact address for the owner of the data.

organisation@modified

attribute is requiredThis attribute contains a time stamp of when you last updated the file. The data type used here follows ISO 8601 recommendations, and we use 'Z' to denote the timezone 'Zulu Time' (UTC). Do not use a local timezone here for simplicity of comparison. Example – 27th of October 2009, at 15 hrs 5 minutes and 30 seconds Zulu would be:

2009-10-27T150530Z

organisation@owner

attribute is requiredDefine an email address that can be used to contact the department/person looking after these files – this is to allow solution providers to contact them should there be a problem. We recommend you to use an alias here to allow you to route the email to the correct department/person rather than a real name here for privacy reasons. From the example:

imda.services@bbc.co.uk

organisation/id

node is requiredWe want to be able to refer to this organisation by a globally unique identifier. This allows solutions to link other services with this organisation that are defined in other XML documents.

organisation/id@crid

attribute is requiredFollowing the advice from RFC 4078 – the value here should be in the form of a Content Reference IDentifier (CRID). For examples of producing CRIDs - please see Section 4 of RFC 4078. In summary the CRID is based on your main domain name, and there is a method of encoding non-URI compliant character sets into UTF-8 compliant serialisation.

organisation/title

node is requiredThis node allows us to identify how an audience member would see the organisation's name, and it allows us to do this in a set of common sizes that are currently used by devices. It also provides the ability to have alternative language support.

title is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/title".

organisation/description

node is requiredThis node allows us to provide a description of the organisation that would be visible to an audience member, and it allows us to do this in a set of common sizes that are currently used by devices. It also provides the ability to have alternative language support.

description is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/description".

organisation/links

node is optionalThis node allows an organisation to provide links to their own internet accessible services – for example a link to their home page on the web, or perhaps their mobile website.

links is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/links".

organisation/tags

node is optionalThe ability to provide free-text 'tags' allows the organisation to provide some useful keywords that describe the organisation. Tags is an optional node.

tags is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/tags".

organisation/genres

node is optionalCategorise your organisation by providing genres that describe the overall service of the organisation. (Note that this is different from categorising the services that are provided by your organisation – this can be done in the brands document). Genres is an optional node.

genres is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/genres".

organisation/logos

node is requiredThis node allows an organisation to provide various logo assets – graphic imagery. So that a solution can provide the correct branding. Since there are a potential infinite number of possible solutions that could use different sizes and formats, we specify here a range of assets that you should provide based on common solutions currently in the industry.

logos is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/logos".

organisation/headquarters

node is requiredIdentify where your organisation resides geographically. The text node of headquarters should contain an id of a location (see below - 'organisation/locations) of 'point' type only.

Tip: for larger organisations specify the head office or headquarters.

Why a location id? As you'll see, locations allow you to specify geographical locations and areas once and reuse them again and again in other xml nodes... like this one. This location may be useful to other specifications. If we use the locations specification it means you can specify the location in any of the ways that the locations specification allows...

organisation/locations

node is required, with 1 or more childrenAs an organisation you may have one or more territories or geographical regions that you target or allow your content to play in. The locations allows you to create simple or complex groupings of geographical data which you can refer to in other appropriate xml nodes (like organisation/headquarters above). Let's take a quick overview of locations:

As you can see, the locations node can be made up of a number of location children, we've shown 4 of the standard location children types (or 'location types'). There is a 5th which isn't shown– one that only contains ref nodes – this simply allows you to group other locations together. You can have multiple location nodes, of same or different types depending on your needs.

Each location type can contain one or more of the 'country' or 'point' or 'poly' or 'postal' or 'ref' nodes - but, as shown, each location type can only contain the nodes shown... in other words, you can't mix 'country' and 'point' in the same location node. In order to do the latter – you can use that 5th type which only has references.

You clearly need to define at least one location as organisation/headquarters requires it. However - the minimum number of locations depends on how many brands and transports that you provide. Rather than trying to complete this data early on when implementing this specification, you will need to add locations as you complete Brands and Transports. However, it's worth making a quick note of what will be expected there.

In Brands you will use location ids to signal a particular location that a brand is associated with – e.g. BBC Radio 4 is located in London, UK. Also in Brands you will signal the brand's editorial relevance in terms of a location – e.g. BBC Radio 4 is globally relevant, but a tightly focused community radio service may only be relevant to a geographic area specified by a polygon.

For Transports, where you are actually specifying the physical streaming information, you will specify two things for every media streaming format and method: any physical restriction you place on a stream, and if the stream itself has a different editorial relevance than it's parent brand (thus allowing you to have multiple streams with, for example, rights blanking identified as editorial relevance). More explanation about this in Transports section.

Locations allows you, as an organisation, to suggest the appropriate geographical reference for something that can be picked up by a solution/aggregator and used to categorise or search.

The powerful feature of locations is that 5th type – which can simply have references to other location nodes inside – this is powerful because it allows you to build areas which can then be grouped together. For example - I may use a country type of location to specify a few countries and give it one ID, then I could specify another location that was the negative of the previous location ID... meaning that I want all the countries not specified to be this location. Another example for this could be: allowing you to specify multiple location's based on postal zones using the postal type and then grouping them together so that you can refer to them using one location ID.

WARNING: There is a danger here that you could create an infinite loop – one location referring to another which refers to that location... and so on. So you will need to be careful to check that you haven't inadvertently created this. It is not possible to model this in XML Schema languages, and so we can't automatically validate without further processing. So locations are both powerful, and potentially complex depending on the number of brands and transports you have. For small organisations with basic rights restrictions or global relevance – this should be relatively straightforward. If not, then keep your wits about you!

Here's a quick example of how you might flex your locations:

.../locations/location@id

attribute is requiredThe id attribute allows you to supply a short name to refer to this location. In other locations we can use this id by prefixing referring to it in the ref nodes. Your location ID should be a string of lower case alphanumeric characters with no spaces or punctuation but could include underscore – the following regular expression specifies how an ID can be formed (this is in our XML Schema for validation but is reprinted here for those not using validation):

^[a-z0-9_]+$

.../locations/location types

Each location node contains an id attribute plus one or more of the following sets of nodes:

Is geo:rss the best thing to use? We answer some questions in our FAQ section about geographical reference systems. We invite feedback should you find that you are unable to represent locations that you need.

Brands Identification

An organisation now needs to present the brands that it has, these are abstracted away from the actual technical information on the streams, and other services, which is held within the transports document. This abstraction lets us keep the editorial information away from the transports and allow us to link services to the brand(s) as needed.

The identification of your brands is made available in a file referenced from the imda.xml root file in imda/brands@url. As we said, we don't mind what this file is called or where it is located – as long as it's publicly available. As an example – our brands identification file could be here:

http://imda.organisation.com/imda_brands.xml

The contents of this file allow an organisation to describe the data that is used visually by a solution to identify the organisation's brand(s) to a consumer, as well as data that is used purely to create links to show ownership of the services identified in other IMDA specifications.

Let's take a look at the main elements of this file:

Reading from the top of this tree, we see that it contains information about:

ID

Identification of brand – this is to allow it to be referenced from elsewhere. This includes a short-id (local to org's data) and a global crid (globally unique).

Type

Identify whether this brand is an 'audio' or 'video' service (for future extension)

Title

Title of brand - in multiple lengths (short, medium, long and extended) and with multiple language support.

Description

Description of brand - in multiple lengths (short, long and extended) and with multiple language support.

Links

Allows org. to associate urls for further information about each brand. e.g. brand's home page on the web, or the brand's mobile service.

Tags

Allows brand to have free-form tagging and key wording. Each tag may signal its weighting to other tags provided, and future extensions may allow categorisation.

Genres

Categorise the brand by Genre.

Intended Audience

Categorise the brand by the intended audience (if appropriate).

Safe

Identify whether this brand follows the terms and conditions where 'safe content' is described.

Logos

Publish logos that solutions can use to represent this organisation.

Spoken

Language(s) editorially relevant to this brand (e.g. main language spoken by brand)

Location

The physical location associated with the brand by using a location id (as defined in the organisation identification document – organisation/locations )

Editorial Relevance

The Editorial relevance of brand in terms of location ids (as defined in the organisation identification document – organisation/locations )

Multiple brands are represented by having multiple brand nodes. Here is a quick example of how all of this could appear in the XML file, again we're using the BBC as the media organisation in this example:

In the above example we've tried to keep things simple, to show some of the ways of describing the data. However – the details begin with our root node for this document: brands.

brands node

node is requiredThe brands node encloses all our metadata that describes our brands. This root node contains information in attributes about the last modified date, an email contact address for the owner of the data and a reference to the organisation that owns the brand(s).

brands@modified

attribute is requiredThis attribute contains a time stamp of when you last updated the file. The data type used here follows ISO 8601 recommendations, and we use 'Z' to denote the timezone 'Zulu Time' (UTC). Do not use a local timezone here for simplicity of comparison. Example – 27th of October 2009, at 15 hrs 5 minutes and 30 seconds Zulu would be:

2009-10-27T150530Z

brands@owner

attribute is requiredDefine an email address that can be used to contact the department/person looking after these files – this is to allow solution providers to contact them should there be a problem. We recommend you to use an alias here to allow you to route the email to the correct department/person rather than a real name here for privacy reasons. From the example:

imda.services@bbc.co.uk

brands@orgcrid

attribute is requiredTo show the ownership of these brands, we refer to the organisation/id@crid value that we specified in the organisation identification file. This is mainly here for convenience, as it allows a solution provider to pick the file up and immediately the data up appropriately where they already have the rest of your IMDA metadata documents. In our ongoing example, the BBC is the organisation, se we put the crid defined in the BBC's organisation identification document here:

crid://bbc.co.uk/

brand

node is required, 1 or moreThere can be one or many of these nodes, each identifying one particular brand from the organisation.

We need to be able to refer to it so we will provide identification in the form of a crid and a short-id. We also need to identify the type of service – is it audio-only or audio+video?

brand@crid

attribute is requiredWe want to be able to refer to this brand by a globally unique identifier – this allows solutions to link other services with the brands that are defined in other XML documents and future services.

Following the advice from RFC 4078 – the value here should be in the form of a Content Reference IDentifier (CRID). For examples of producing CRIDs - please see Section 4 of RFC 4078. In summary the CRID is based on your main domain name, and there is a method of encoding non-URI compliant character sets into UTF-8 compliant serialisation.

brand@id

attribute is requiredThis is a short-id and an organisation makes no guarantee that it is globally unique. The uniqueness should be local to the organisation. This can be a short-hand, if you prefer, used in the IMDA metadata documents where repeating the full crid isn't necessary as the link is implied by the structure and hierarchy of the metadata documents.

Your short-id should be a string of alphanumeric lower case characters which contain no other punctuation or other symbols apart from '_' (underscore). The string should follow the following regular expression:

^[a-z0-9_]+$

brand@type

attribute is requiredTo identify the type of a brand - whether it is an audio-only or an audio and video service. In this version of the Service Identification document the only valid value for the attribute is 'audio'.

This is merely here to allow future expansion of the specification to other types of services.

In the future the attribute may contain 'audio' or 'video'. For example - a 'radio' brand would be audio-only service, and a TV brand would be video. Currently this specification is predominately for audio-only brands – so it is currently unnecessary to represent brands which are video services – this is for future use.

brand/title

node is requiredThis node allows us to identify how an audience member would see the brand's title (or name), and it allows us to do this in a set of common sizes that are currently used by devices. It also provides the ability to have alternative language support.

title is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/title".

brand/description

node is requiredThis node allows us to provide a description of the brand that would be visible to an audience member, and it allows us to do this in a set of common sizes that are currently used by devices. It also provides the ability to have alternative language support.

description is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/description".

brand/links

node is optionalThis node allows an organisation to provide links relevant to the brand about links to internet accessible services – for example a link to the home page of the brand on the web, or perhaps its mobile website.

links is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/links".

brand/tags

node is optionalThe ability to provide free-text 'tags' allows the organisation to provide some useful keywords that describe the brand. Tags is an optional node.

tags is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/tags".

brand/genres

node is requiredCategorise your brand by providing genres that describe it. (Note that this is different from categorising the organisation itself – this can be done in the organisation document). Genres is an optional node.

genres is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/genres".

brand/intendedaudience

node is optionalTo allow a solution to understand the type of audience that would perhaps find your brand more suitable then you can optionally categorise by identifying the 'intended audience' of your brand in the intendedaudience node.

If you choose to categorise your brand(s) in this way, we have decided to adopt TV-Anytime's Intended Audience specification, specifically version 1.5.1 of their specification.

TV-Anytime is an "association of organizations which seeks to develop specifications to enable audio-visual and other services based on mass-market high volume digital storage in consumer platforms." ~ TV-Anytime website

The published document for version 1.5.1 of their specification is referred to as: "ETSI TS 102 822-3-1 V1.5.1 (2009-05)" and the full xml document with the options is available in Appendix A.7 (on page 113). This specification is available from the ETSI website.

You can have one or more audience child nodes of intendedaudience and each child should be considered by the solution as additive. Example: specifying several specific age groups means that the brand is intended by the organisation of each of those groups.

The IMDA has republished the TV-Anytime xml document here for simplicity: tva_IntendedAudienceCS_v151.xml

Use the Term@TermID reference in the text node of our audience node.

An example of how an intendedaudience node may appear:

brand/safe

node is requiredA simple identification of whether a brand is of 'safe content' as described in your root document. The text node of safe should contain a boolean string - either 'true' or 'false'.

Use lower case – no spaces or punctuation – otherwise the aggregator/solution provider will assume it is false.

brand/logos

node is requiredThis node allows an organisation to provide various logo assets – graphic imagery – relevant to the brand. So that a solution can provide the correct branding. Since there are a potential infinite number of possible solutions that could use different sizes and formats, we specify here a range of assets that you should provide based on common solutions currently in the industry.

logos is a node that is shared in several documents – the implementation details are available in the Shared Nodes section titled "[organisation|brands/brand]/logos".

brand/spoken

node is requiredThis node allows you to identify the language(s) editorially relevant to this brand (e.g. main language spoken by brand). The text node of spoken should contain languages as defined in RFC 5646. For multiple languages please provide them bar delimited (e.g. 'sl-rozaj|de-DE' - which would mean Resian dialect of Slovenian and the German used in Germany)

Please note that RFC 5646 obsoletes the following chain of RFC documents: RFC 4646 < RFC 3066 < RFC 1766.

brand/location

node is requiredIdentify where the brand resides geographically. The refid attribute of location should contain an id of a organisation/locations/location@id of 'point' type only (see 'organisation/locations).

Tip: you should pick a particular spot where the brand has it's office or headquarters. Please note that this is distinct from the brand/editorialrelevance (below) which is used to describe the location(s) of where this brand is editorially relevant to.

Why a location id? As you'll see, locations allow you to specify geographical areas once and reuse them again and again in other xml nodes... like this one. This location may be useful to other specifications. Locations are defined in organisation/locations.

brand/editorialrelevance

node is optionalIdentify the editorial relevance of the brand to particular regions by using any type of organisation/locations/location@id in the refid attribute of editorialrelevance. (see 'organisation/locations').

This is useful to solutions which may, at first or on request, present the audience with content which is somehow more relevant to them geographically. For example – if an audience member in Singapore is using a solution then they may be looking for local news services, and so the solution may use the editorial relevance provided here to help it decide whether this content should be shown nearer the top of the results. However this doesn't mean that your content wouldn't be presented, it may just mean that it appears further down the results as it is perhaps to be less relevant.

Transports Identification

Once the brands themselves have been identified we need to provide information about how a solution can allow an audience member to be able to play back the brand's content. In other words – to allow a solution to provide the correct stream for the organisation's brand. We will call the various technical ways you can get the content as 'transports'.

The transports document is perhaps one of the more complicated specifications, yet it is hopefully powerful and scalable to future editions of the IMDA Service Identification documents. It should also be noted that this edition of the Service Identification docs assumes your brand's transports describe live, or simulcast, content – we are currently working on how to represent on-demand services, and downloads (e.g. podcasts)

Each brand identified in the Brands document can have one or more transports. A quick overview of this is as follows:

In this overview we have kept the transport node without it's various children just to keep the overview simple. Using our favourite example Organisation, the BBC, here's an example of how the shell of the document might look (the content of the transport nodes is left out for simplicity at this stage):

The first thing you should notice is that the root transports node looks a lot like the same as our brands document – with an orgcrid attribute to link it to our organisation, a modified timestamp and an owner email address. The direct descendents of transports are brand nodes which merely allow us to group subsequent technical transport information together by the brand they refer to (from the brands document).

That technical transport information is then identified by transport nodes.

Let us now look at the structure in detail.

transports node

node is requiredThe transports node encloses all our metadata that describes the ways in which a solution could receive the content of our brands. This root node contains information in attributes about the last modified date, an email contact address for the owner of the data and a reference to the organisation that owns the transport(s).

transports@modified

attribute is requiredThis attribute contains a time stamp of when you last updated the file. The data type used here follows ISO 8601 recommendations, and we use 'Z' to denote the timezone 'Zulu Time' (UTC). Do not use a local timezone here for simplicity of comparison. Example – 27th of October 2009, at 15 hrs 5 minutes and 30 seconds Zulu would be:

2009-10-27T150530Z

transports@owner

attribute is requiredDefine an email address that can be used to contact the department/person looking after these files – this is to allow solution providers to contact them should there be a problem. We recommend you to use an alias here to allow you to route the email to the correct department/person rather than a real name here for privacy reasons. From the example:

imda.services@bbc.co.uk

transports@orgcrid

attribute is requiredTo show the ownership of these brands, we refer to the organisation/id@crid value that we specified in the organisation identification document. This is mainly here for convenience, as it allows a solution provider to pick the file up and immediately the data up appropriately where they already have the rest of your IMDA metadata documents. In our ongoing example, the BBC is the organisation, so we put the crid defined in the BBC's organisation identification document here:

crid://bbc.co.uk/

transports/brand

node is required, same number of nodes as brands described in brands documentThis node is merely a tool to allow grouping all technical information for a particular brand together. You show the link to the brand by using the brand@id attribute and we identify the type of service these transports provide for this brand by entering the brand@type attribute. These are as follows:

transports/brand@id

attribute is requiredThis attribute should contain the id of the brand from your brands document (specifically: brands/brand@id) – this is the 'short' id, rather than the full crid. For the purposes of showing a link here, a local id is fine rather than the globally unique crid.

transports/brand@type

attribute is requiredThis attribute allows you to identify the type of transports you are going to define. In this edition of the Service Identification documents we have only 1 currently valid value for type:

The following table is our proposal for future editions of these Service Identification document and we print our initial ideas now to provoke feedback and comment from media organisations and solutions alike. As an organisation or a solution provider you not currently use these types in your document – this will likely change and coalesce into future Guideline's edition.

transports/brand/transport

node is required, 1 or more depending on number of transport typesThese are used to group technical information about a specific type of transport mechanism together. In this current set of IMDA Service Identification documents we define the first three types of transport that are of use immediately to organisations and solutions:

We'll now look at these in detail.

transport@type : ip_direct or broadcast

The transport type ip_direct or broadcast are very similar, allowing for us to keep a consistant method of grouping information together to describe technical information that can be used by a solution to select the most appropriate ways of connecting to and playing back content associated with the brand where the content is available via the public internet ('ip_direct') or via a broadcast medium ('broadcast').

The children of this transport type are one or more media nodes.

These media nodes are groupings of streaming service types (e.g. Windows Media Services).

Children of media nodes are one or more stream nodes which actually contain the technical information that would allow a solution to connect and play back.

A quick overview of this follows:

Here is an example of how this node might appear:

We will now describe the detail of media and stream nodes:

transport/media

nodes is requiredTo allow grouping streaming service types together our media nodes contain a single attribute – type. This can contain one of the following values:

These types are the most common right now that fit with the IMDA's Technical profiles, we will be adding further types here as new editions of this specification are provided – please get involved with the IMDA and provide feedback to help set how new editions are formed.

Why didn't we include Flash Media Server delivered services here, given how common they are? The answer is simply that they are not a priority in this edition, and require further discussion about how to correctly map the required information to allow a technical solution to connect to them. For example – many FMS services vary in one way or another, including having digital rights management that differs from one media organisation to the next.

This is clearly an area where we will have more streaming service types in the future – please help us shape future Service Identification document editions by providing feedback and comment about this area.

transport/media/stream

nodes is requiredThe stream node contains much technical information provided by the organisation to help solutions provide or pick the most appropriate stream for the brand. As an organisation you may find that you only need to list one stream node as a child of media – the ability to list multiple streams is required when you have multiple different encode or delivery profiles.

For example – you may have two Windows Media streams at two different bitrates as unique streams (no IntelliStream or Multi-bitrate streaming). Or you may have two streams that have the same encoding profile but are delivered from a different server farm in different locations (geographical areas).

There are quite a few attributes possible within stream, but it is important to understand that there are only two required as a minimum: @url, @audiocodec

The rest either have defaults, or you provide a value for an attribute to provide guidance to a solution.

Best practice guidance: note that the more optional attributes that you complete, the more likely a solution will be able to easily add you. If you only complete the minimum, the solution will have to investigate your streaming techniques. By completing more of the optional attributes you will help the solution to correctly list you. Some media organisations may not have all this information to hand as they may use a third-party to actually do their streaming for them – if you are one of those organisations we would encourage you to speak to your third-party and show them the optional attributes here and ask them to help you provide more information. Remember – some solutions will balance the work they need to do against the need to list you.

The attributes within our stream nodes are as follows:

.../stream@physical

attribute is optional if transport type is not broadcast, required otherwiseThe physical availability of the stream – a backreference to a location id (see organisation/locations). The location cannot be a 'point' type location (see "locations/location types"). This is an optional attribute, unless this is a broadcast transport type then it is a required attribute. If empty or no attribute (implied) then assume no restriction.

Note for an organisation this isn't a replacement for managing your rights on your servers, but merely to allow a solution to present appropriate services to a user – if they are not physically going to be able to play it, then don't offer it. To be explicitly clear: this means that a solution may not list you to the audience.

.../stream@relevance

attribute is optionalThe editorial relevance of the stream - a backreference to a location id (see organisation/locations). This is an optional attribute. If empty or no attribute (implied) then assume global relevance. Relevance is an opportunity for an organisation to offer guidance to the solution about any editorial relevance issues on a geographic basis.

.../stream@url

attribute is requiredRequired. Provide the URL where a metafile or stream is exposed that can be 'played' by solutions, or provide a link that describes how to receive a broadcast service. The contents of this attribute are dependent on the transports/brand/transport@type value, and the following sections identify the appropriate rules you should follow to complete the @url attribute:

@url values where transport@type is ip_direct or ip_indirect

The @url attribute should contain the public internet URL of the stream, page or playlist that allows playback of the brand. For example:

http://bbc.co.uk/radio/listen/live/r1.asx

@url values where transport@type is broadcast

The @url attribute should contain a URL, or similar identifier, which signals to the aggregator or solution how to locate the broadcast within the broadcast standards specified in the @media attribute of the parent transport node. For many broadcast services there isn't an existing standard for identifying services in a similar way, so we look to providing a URL made up of the media type as the 'protocol' and then identifiers within the broadcast service itself which identify the particular media associated with the brand.

Since there is specific advice depending on the value of the @media attribute we have detailed this in the following table:

.../stream@min-bitrate

attribute is optionalThe value of min-bitrate should be in bits per second (bps). Specify the lowest logical bit rate of the stream here. This is to allow solutions to offer stream playback where the bandwidth on the client may not be enough for one stream, but is for another – e.g. you might offer two streams one at a high bitrate, the other at a low bitrate. Note that min-bitrate and max-bitrate (below) allow you to show the min and max for a multi-bitrate stream, if the stream is only one bitrate then the min and max should be entered as the same. If the stream uses a variable codec, please specify the average value or the minimum value.

This is an optional attribute. You must either specify min-bitrate and max-bitrate - or neither.

Example: 131072

.../stream@max-bitrate

attribute is optionalThe value of max-bitrate should be in bits per second (kbps). Specify the highest logical bit rate of the stream here. This is to allow solutions to offer stream playback where the bandwidth on the client may not be enough for one stream, but is for another – e.g. you might offer two streams one at a high bitrate, the other at a low bitrate. Note that min-bitrate (above) and max-bitrate allow you to show the min and max for a multi-bitrate stream, if the stream is only one bitrate then the min and max should be entered as the same. If the stream uses a variable codec, please specify the peak value.

This is an optional attribute. You must either specify min-bitrate and max-bitrate - or neither.

Example: 131072

.../stream@audiosamplerate

attribute is optionalSpecify the audio sample rate, in Hertz, of the stream's audio component.

This is an optional attribute.

Example: 44100

.../stream@protocol

attribute is optionalThe value of the protocol attribute should be the protocol or protocols used by the streaming servers for this stream. You may list one or more of the following values, where you list multiple values use a '|' (bar) to delimit the list.

In this edition of the specification, the values are: http, rtsp

Please note that the order of protocols in the list does not convey any meaning to the solution. The solution determines which protocols to use, and it may be limited by the protocols available to it.

For example – a Windows Media stream may be available via RTSP and HTTP protocols so your protocol value would be: http|rtsp

This is an optional attribute. If empty or omitted, the solution would need to test which protocols are available.

.../stream@method

attribute is optionalThe method of the stream is merely there to allow you to distinguish unicast streams from multicast streams – and so the possible values here are either unicast or multicast.

This is an optional attribute. If empty or omitted the implied value is unicast.

.../stream@audiochannels

attribute is optionalThe value of audiochannels is an integer that corresponds to the number of audio channels in the stream – for example, if the stream is mono audio this value would be '1', for stereo audio it would be '2'.

This is an optional attribute. If empty or omitted the implied value is 2.

.../stream@audiocodec

attribute is requiredRequired. The audiocodec attribute is the IMDAs attempt to create a shared vocabulary around codecs used for audio streaming, or the audio component of an a/v stream.

stream/radiodns

node is optionalThe radiodns optional node is provided for media organisations who provide services as defined by the RadioDNS Organisation. For further information on the use of this node please see the section on 'RadioDNS'.

transport@type : ip_indirect

This should be considered as a secondary transport type. We will use it to describe technical information that can be used by a solution to offer public internet accessible services offered by the brand which may not allow a direct connection and play back via a streaming services. For example – this allows an organisation to offer alternative ways to experience the brand's content on the internet where the service does not lend itself to direct connection by the solution.

There is only one child node type here and it simply uses our shared links node as described in '[organisation|brands/brand]/links'.

Here is an example of this transport type, again using the BBC to aid in understanding:

In this example we use a links node to describe a couple of services – one for 'screen' and one for 'handheld'. The url attributes contain links to the BBC's web-based iPlayer service formatted for 'screen' and 'handheld'. Because the links node, and its children, are defined elsewhere we won't repeat the detail here.

transport@type : the future

Please provide feedback and comment if there are any additional transport types, or their media types, you would like to see supported in the future.

transport/brand/radiodns

node is optionalThe radiodns optional node is provided for media organisations who provide services as defined by the RadioDNS Organisation. For further information on the use of this node please see the section on 'RadioDNS'.

Additional features

This section deals with additional features a Media Organisation may expose in relation to the transports for their brands. They are entirely optional and merely allow a Media Organisation to expose further information. Appearance of these features in the Service Identification does not necessarily mean that an Aggregator, Manufacturer or solution would use this information - it is entirely up to the popularity of the feature whether it is supported.

RadioDNS

Website: radiodns.org

node is optional, attributes inside node are required if node is used

"RadioDNS is a collaborative project to enable the convergence of radio broadcasting and IP-delivered services. It aims to significantly enhance the experience of radio listening using scalable and resilient broadcast technology in tandem with additional information via IP." ~ radiodns.org

For more information on the RadioDNS concepts we refer you to the website. Media Organisations are able to expose RadioDNS functions by signalling them as either:

1. a child node of transports/brand – to signify that the RadioDNS details specified are related to the entire brand. (See Example A below)
2. a child node of transports/brand/transport/media/stream nodes – to signify that the RadioDNS details specified are related to the particular stream. (See Example B below)

The RadioDNS node that we provide in the IMDA Service Identification is:

<radiodns fqdn="a.fully.qualified.domain.name" sid="serviceid" />

We imagine that a fairly simple RadioDNS provision by a Media Organisation would use the 1st option above – making a single radiodns node a child of transports/brand for each brand node.

Example A – as a child of transports/brand :

Example B – as a child of transports/brand/transport/media/stream :

For details about values for the fully qualified domain name attribute (fqdn) and the service id attribute (sid) please examine the specifications provided by the RadioDNS organisation.

RadioDNS specification available here: http://radiodns.org/documentation/ (RDNS01: Technical Specification, RDNS02: Administration and Governance, RDNS03: Potential applications and use cases)

Your feature here!

If you have information on an additional feature which exposes more information about a Media Organisations' brands or transports – please get in touch and provide feedback.

Manifests Identification

In order to provide information to a solution about schedule information, or more data on what is available for editorial programming in relation to a particular brand, we provide information in a file referenced from the imda.xml root file in imda/manifests@url. As we said, we don't mind what this file is called or where it is located – as long as it's publicly available. As an example – our manifests identification file could be here:

http://imda.organisation.com/imda_manifests.xml

The contents of this file allow an organisation to describe data that provides further information about what is available from brands – this could be schedule data regarding programming, or perhaps podcast feeds related to the brand.

If you do not have any manifests - then you don't need a manifests document, it's entirely optional.

Let's take a look at the main elements of this file:

Our manifests document is made up of a manifests node, and one or more manifest children. Each manifest child has a type and a format to identify the general type of the manifest and the specific format of that type. The specific type and format combination will dictate the subsequent make up of the child nodes within your manifest node – these variants are described below after a quick example of how all this could appear in an XML file example:

In the above example we've tried to keep things simple, to show some of the ways of describing the data. However – the details begin with our root node for this document: manifests.

Let us now look at the different types of manifests that you can have, and their structure in more detail.

manifest@type

attribute is requiredThere are currently two manifest types in this version of the specification, more types may become available in future specifications. The different types are defined in the table below:

For each of these values, the content of the manifest child differs. The following describes these differences, allowing you to pick and choose which services you wish to include.

manifest/format

node is required, attributes requiredEach type of manifest may have several distinct formats and this is signalled in the format node – we have defined several formats in this version of the specification, more formats may become available in future specifications. The node contains one attribute: name. In order to signal which format you wish this manifest node to contain - the format@name should contain one of the following values described in the table below:

For each of these values, the content of the manifest child differs. The following describes these differences, allowing you to pick and choose which services you wish to include.

manifest[@type='epg']/format[@name='dabepg']

This manifest format allows you to link schedule information described in 'DAB EPG XML' documents provided by the media organisation to the brands as defined in the IMDA SI documents. This means that a solution can access data on the editorial programming associated with a live stream in ip_direct transport types, or the broadcast services in broadcast transport types.

For full details on how the DAB EPG XML should be coded, please refer to the ETSI standard TS 102 818 provided by the WorldDMB organisation. For the IMDA SI manifests document - these XML files containing the data need to be available at URL accessed via HTTP (or HTTPS if the media organisation is using protection).

The following child nodes for this format allow the media organisation to signal where the DAB EPG XML files are stored, and how they link to the brands defined in the IMDA SI Brands document. Here is an example of a manifest node that links to a fictional DAB EPG XML location and maps it to some brands.

basetimezone

node and its attribute is requiredIn order for solutions working across various timezones, it is important for the media organisation to identify the home timezone for the schedules contained within the DAB EPG XML. This should match the basis used for the 'startTime' values in the DAB EPG XML.

The basetimezone has one required attribute called tz and the value of this value should follow the 'Olson' timezone specifications.

si

node is requiredThe DAB EPG XML specifies a 'Service Identification' document - this node allows you to link this in to the IMDA SI document. Since the DAB EPG XML files identify a shifting window of time then we allow here for 'macros' which you can use to get the correct DAB EPG XML file based on the current date.

si@urlpattern

attribute is requiredThe urlpattern value should be an absolute URL to the location of the Media Organisations DAB EPG XML Service Identification (SI) file. Because of the shifting time window specified by the DAB spec, this absolute URL should contain 'macros' where dates are specified in the filename or path. Please see section below for information about what 'macros' are available. This URL may be HTTP or HTTPS depending on whether the media organisation is using protection.

Reminder: URLs to your data in si@urlpattern can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

pi

node is requiredThe DAB EPG XML specifies 'Programme Information' documents - this node allows you to link this in to the IMDA SI document. Since the DAB EPG XML files identify a shifting window of time then we allow here for 'macros' which you can use to get the correct DAB EPG XML file based on the current date.

pi@urlpattern

attribute is requiredThe urlpattern value should be an absolute URL to the location of the Media Organisations DAB EPG XML Programme Information (PI) files. Because of the shifting time window specified by the DAB spec, this absolute URL should contain 'macros' where dates are specified in the filename or path. Please see section below for information about what 'macros' are available. This URL may be HTTP or HTTPS depending on whether the media organisation is using protection.

Reminder: URLs to your data in pi@urlpattern can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

gi

node is optionalThe DAB EPG XML specifies a 'Grouping Information' document - this node allows you to link this in to the IMDA SI document. Since the DAB EPG XML files identify a shifting window of time then we allow here for 'macros' which you can use to get the correct DAB EPG XML file based on the current date.

gi@urlpattern

attribute is requiredThe urlpattern value should be an absolute URL to the location of the Media Organisations DAB EPG XML Grouping Information (GI) file. Because of the shifting time window specified by the DAB spec, this absolute URL should contain 'macros' where dates are specified in the filename or path. Please see section below for information about what 'macros' are available. This URL may be HTTP or HTTPS depending on whether the media organisation is using protection.

Reminder: URLs to your data in gi@urlpattern can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

mapping

node is requiredNow that we know the urlpatterns for the SI, PI and GI DAB EPG XML files we specify the important keys that link the data inside these files with the brands in the IMDA SI document via the brand ids. The mapping node also allows the media organisation to provide the valid values of the '[SERVICEFILENAME]' macro, more about this in the section below.

All attributes of the mapping node are required.

mapping@type

attribute is requiredIdentifies the node in the DAB EPG XML that we will use to link the value of the value attribute to our brand id in the refid attribute. The default value of this attribute is 'serviceScope'.

mapping@value

attribute is requiredThis is the value that should be used to link the node in the DAB EPG XML (by default 'serviceScope') with the brand id in refid attribute.

mapping@servicefilename

attribute is requiredThe value of servicefilename defines what to put in the urlpattern of the pi node to find the data for this service so that it can link to the IDMA SI brand (in the refid attribute).

mapping@brandid

attribute is requiredThe brand id from the IMDA SI Brands document - this is the brand which the media organisation wishes to signal as being related to the Programme Information found by flattening the urlpattern of the pi, given the servicefilename.

urlpattern macros

The urlpattern attributes contain URLs which have a number of path or filename elements which may vary depending on the current date, or the service in the DAB EPG XML files. The following table describes what each macro means, and how it should be used. Macros use the style [VARIABLE]because square brackets are not allowed in regular URLs, meaning that they are obviously not a valid URL until the macro is swapped out for a valid value. Please note that filename patterns are covered in Annex C of the ETSI DAB EPG XML documentation.

manifest[@type='epg']/format[@name='dabepg_drm']

This manifest format is merely a variant of the manifest format dabepg. The child nodes are the same as for dabepg however the only difference that the servicefilenames make up is different in the DAB EPG XML.

Why duplicate the dabepg format? Why have a variant for drm services? It's simply because a media organisation may have a set of DAB services and DRM services. Because the DRM services are identifed slightly differently in the DAB EPG XML, we need to keep it separate in the IMDA SI Manifests document specification.

manifest[@type='epg']/format[@name='xmltv']

This manifest format is provided to allow a media organisation who publishes their schedule data using the XMLTV schema.

XMLTV is a specification used by many Open Source projects that use EPG data about Television services, though it can be used for Radio services. More information is available from the XMLTV Wiki and also MythTV's XMLTV resources page.

A quick example of how this node might appear:

Reminder: URLs to your schedule data in the XMLTV format can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

basetimezone

node and its attribute is requiredIn order for solutions working across various timezones, it is important for the media organisation to identify the home timezone for the schedules contained within the this manifest.

The basetimezone has one required attribute called tz and the value of this value should follow the 'Olson' timezone specifications.

mapping

node is requiredWe specify here a URL for a web page that describes the schedule information for a brand – by defining a mapping between our brand's brandid and an XPath definition, as defined in the xpath attribute, which allows an aggregator to find the root node of the information relating to the particular brand.

All attributes of the mapping node are required.

mapping@brandid

attribute is requiredThe brandid from the IMDA SI Brands document - this is the brand which the media organisation wishes to signal as being related to the schedule infromation held at the url.

mapping@url

attribute is requiredThe url attribute contains the uniform resource locator which points to an XML document which follows the XMLTV format.

Reminder: URLs to your schedule data in the XMLTV format can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

mapping@xpath

attribute is requiredThe xpath attribute contains the an xpath expression that can be used against the XMLTV document as located in the url attribute to select the node of the tree that contains schedule information that pertains to the brand specified in brandid.

manifest[@type='epg']/format[@name='webepg']

This manifest format is provided to allow a media organisation who publishes their schedule data on publicly accessible pages built up of HyperText Markup Language (HTML). Some media organisations publish their schedule information on these 'web pages', the structure of which typically doesn't follow any other particular structured electronic programme guide standard.

A quick example of how this node might appear:

The webepg manifest format is included to allow Media Organisations to link to existing web-accessible pages, perhaps on their website, that contains schedule data about a brand's programming. This is classed as unstructured in that it doesn't necessarily conform to any specification that has shared understanding, it is only structured in the sense that it should be written in HTML markup. If a Media Organisation chooses to use this format they should be aware that an aggregator may take longer to list schedule data, or not list the schedule data at all. It is strongly recommended that you provide schedules using the other more structured XML manifest formats available here.

basetimezone

node and its attribute is requiredIn order for solutions working across various timezones, it is important for the media organisation to identify the home timezone for the schedules contained within the this manifest.

The basetimezone has one required attribute called tz and the value of this value should follow the 'Olson' timezone specifications.

specification

node is optional, but if node is specified the attribute is requiredIf you have a document that defines the specification of your schedule web pages in HTML, then please provide a link using the specification node. Put the URL to the specification documentation in the specification@url attribute. This node is optional, but please consider that without guidance from a specification an aggregator will be even less likely to list your schedule data.

mapping

node is requiredWe specify here a URL for a web page that describes the schedule information for a brand – by defining a mapping between our brand's brandid and a webpage url.

All attributes of the mapping node are required.

mapping@brandid

attribute is requiredThe brandid from the IMDA SI Brands document - this is the brand which the media organisation wishes to signal as being related to the schedule infromation held at the url.

mapping@url

attribute is requiredThe url attribute contains the uniform resource locator which points to a web page built using Hypertext Markup Language (HTML). The web page contains schedule information.

If you have provided a specification in this manifest node, this HTML web page should follow what is documented there.

Reminder: URLs to your schedule data in web pages can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

manifest[@type='podcast']/format[@name='rss20']

This manifest format is provided to allow a media organisation who publish episodic media via the podcast mechanism using RSS 2.0 formatted XML files.

"A podcast is a series of digital media files (either audio or video) that are released episodically and often downloaded through web syndication. The word replaced webcast in common use with the success of the iPod and its role in the rising popularity and innovation of web feeds." ~ WikiPedia entry for 'Podcast'

It is valid to link to RSS 2.0 formatted files that use the Media RSS module specified by Yahoo!.

Media organisations that use OPML 1.0 (Outline Processor Markup Language verision 1.0) to aggregate a group of RSS 2.0 syndicated programmes together, can specify the location of the aggregate document in this section.

The RSS 2.0 specification is available at:

http://www.rssboard.org/rss-specification

The MEDIA:RSS module specification version 1.5.0 is available at:

http://video.search.yahoo.com/mrss

The OPML 1.0 specification is available at:

http://dev.opml.org/spec1.html

In order to demonstrate the flexibilities of this node – there are at least four different ways it could be used:

1. A single 'podcast' can be related to a particular Brand by providing a mapping between where the RSS is available for the 'podcast' and the brand id that it should relate to.
2. Multiple 'podcasts' can be related to a particular Brand by having more than one of these mappings with the same brand id.
3. Multiple 'podcasts' can be related to a particular Brand by providing a mapping between where the OPML is available for the aggregated list of 'podcasts' and the brand id.
4. A combination of mappings – links to RSS, or OPML files, is possible for complex scenarios.

A quick example of how this node might appear:

Reminder: URLs to your 'podcasts' can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

basetimezone

node and its attribute is requiredIn order for solutions working across various timezones, it is important for the media organisation to identify the home timezone for the podcasts contained within the this manifest. Although the RSS file linked to will present a timezone in the rss/channel/item/pubDate related to each episode, it is useful to know beforehand.

The basetimezone has one required attribute called tz and the value of this value should follow the 'Olson' timezone specifications.

mapping

node is requiredWe specify here a URL to the RSS 2.0 formatted XML file that describes the podcasts for a particular brand – by defining a mapping between our brand's brandid the podcasts represented in the linked RSS.

A variant of this node allows for OPML formatted XML files to be linked in the URL attribute. If you wish to use an OPML file here – the mapping node should include the xpath attribute which contains the XPath definition which allows an aggregator to find the root OPML:outline node of the information relating to the particular brand.

All attributes of the mapping node are required.

mapping@brandid

attribute is requiredThe brandid from the IMDA SI Brands document - this is the brand which the media organisation wishes to signal as being related to the podcast infromation held at the url.

mapping@url

attribute is requiredThe url attribute contains the uniform resource locator which points to an XML document which follows the RSS 2.0, unless the xpath attribute is used in which case the XML document should follow the OPML format.

Reminder: URLs to your podcasts can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

mapping@xpath

attribute is optional – if specified then the contents of @url should be formatted as OPMLThe xpath attribute contains a valid xpath expression that can be used against the OPML document to select the appropriate outline node that links to the RSS 2.0 resource related to the brand specified in brandid.

manifest[@type='podcast']/format[@name='atom10']

This manifest format is provided to allow a media organisation who publish episodic media via the podcast mechanism using ATOM Syndication Format 1.0 (known as 'Atom 1.0') formatted XML files.

"A podcast is a series of digital media files (either audio or video) that are released episodically and often downloaded through web syndication. The word replaced webcast in common use with the success of the iPod and its role in the rising popularity and innovation of web feeds." ~ WikiPedia entry for 'Podcast'

Media organisations that use OPML 1.0 (Outline Processor Markup Language verision 1.0) to aggregate a group of ATOM 1.0 syndicated programmes together, can specify the location of the aggregate document in this section.

The ATOM Syndication Format 1.0 specification is available as RFC 4287:

http://tools.ietf.org/html/rfc4287

The OPML 1.0 specification is available at:

http://dev.opml.org/spec1.html

In order to demonstrate the flexibilities of this node – there are at least four different ways it could be used:

1. A single 'podcast' can be related to a particular Brand by providing a mapping between where the ATOM feed is available for the 'podcast' and the brand id that it should relate to.
2. Multiple 'podcasts' can be related to a particular Brand by having more than one of these mappings with the same brand id.
3. Multiple 'podcasts' can be related to a particular Brand by providing a mapping between where the OPML is available for the aggregated list of 'podcasts' and the brand id.
4. A combination of mappings – links to ATOM feeds, or OPML files, is possible for complex scenarios.

A quick example of how this node might appear:

Reminder: URLs to your 'podcasts' can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

basetimezone

node and its attribute is requiredIn order for solutions working across various timezones, it is important for the media organisation to identify the home timezone for the podcasts contained within the this manifest. Although the ATOM feed linked to will present a timezone in the feed/entry/updated related to each episode, it is useful to know beforehand.

The basetimezone has one required attribute called tz and the value of this value should follow the 'Olson' timezone specifications.

mapping

node is requiredWe specify here a URL to the ATOM Syndication Format 1.0 formatted XML file that describes the podcasts for a particular brand – by defining a mapping between our brand's brandid the podcasts represented in the linked ATOM feed.

A variant of this node allows for OPML 1.0 formatted XML files to be linked in the URL attribute. If you wish to use an OPML file here – the mapping node should include the xpath attribute which contains the XPath definition which allows an aggregator to find the root OPML:outline node of the information relating to the particular brand.

All attributes of the mapping node are required.

mapping@brandid

attribute is requiredThe brandid from the IMDA SI Brands document - this is the brand which the media organisation wishes to signal as being related to the podcast information held at the url.

mapping@url

attribute is requiredThe url attribute contains the uniform resource locator which points to an XML document which follows the ATOM Syndication Format 1.0, unless the xpath attribute is used in which case the XML document should follow the OPML 1.0 format.

Reminder: URLs to your podcasts can be available via HTTP or HTTPS - and basic authentication may be used for protection. See "Protecting your metadata" for further information.

mapping@xpath

attribute is optional – if specified then the contents of @url should be formatted as OPMLThe xpath attribute contains a valid xpath expression that can be used against the OPML document to select the appropriate outline node that links to the ATOM 1.0 resource related to the brand specified in brandid.

Your favourite manifest type or EPG format here!

If you have information on an additional type or format of manifest, including a common EPG format, which you feel is important we support – please get in touch and provide feedback.

Shared Nodes

[organisation|brands/brand]/title

node is required, see advice about childrenThe title node allows us to present the organisation's title or the organisations brand's name in a set of common sizes that are currently used by devices. It also provides the ability to have alternative language support.

The children of title are short, medium, long and extended and allow the organisation to provide how they wish their titles to appear where text may be limited to certain sizes. These were decided based on existing specifications that had considerations to how solutions may present an organisation's name. One of the specifications that was used as a good example was the ETSI TS 102.818, a.k.a. the 'DAB EPG SI' specification.

A summary of the allowable lengths for the various text nodes of the children are:

The lang attribute of those children should contain an entry from RFC 5646 that identifies the language of the enclosed text node. A key part of this RFC is section 4, which includes information about how to choose and how to interpret language tags.

The title node can contain one or more children of the same type, if the lang is different. This allows you to, for example, have multiple short children but in different languages.

Best practice recommendation: as an organisation you should have at least an English language option for any short, medium, long or extended nodes. This is important as in many cases the solution may have a default display that uses English, or it may be that a hardware limitation means that a display can not support all character sets (quite often this is because a hardware decision was made since the number of services with a minority language doesn't make it sensible to pay for a display which can actually present that language where the hardware is limited). Even if your default language would be non-English you should consider having an English version of your title.

Best practice recommendation: don't use a title entry if it contains less characters than the shorter type before it. But you must specify the 'short' title as a minimum. For example – if your title is 15 characters and you have no longer variants then you will provide a 'medium' title here, and you must create a shorter version for 'short' title to comply with the minimum requirements.

From the example above this could appear in your xml like this – a simple example with just a short and long title all in English (Great Britain):

Another example – demonstrating French and English versions of short, medium and long titles:

[organisation|brands/brand]/description

see parent document advice for node requirement, child requirements advice can be found belowThis node allows us to provide a description of the organisation or the brand that would be visible to an audience member, and it allows us to do this in a set of common sizes that are currently used by devices. It also provides the ability to have alternative language support.

The children of description are short, long and extended and allow the organisation to provide a description of the organisation, or brand, where text may be limited to certain sizes. These were decided based on existing specifications that had considerations to how solutions may present an organisation's description. One of the specifications that was used as a good example was the ETSI TS 102.818, a.k.a. the 'DAB EPG SI' specification.

A summary of the allowable lengths of the for the various text nodes of the children are:

The lang attribute of those children should contain an entry from RFC 5646 that identifies the language of the enclosed text node. A key part of this RFC is section 4, which includes information about how to choose and how to interpret language tags.

The description node can contain one or more children of the same type, if the lang is different. This allows you to, for example, have multiple short children but in different languages.

Best practice recommendation: as an organisation you should have at least an English language option for any short, long or extended nodes. This is important as in many cases the solution may have a default display that uses English, or it may be that a hardware limitation means that a display can not support all character sets (quite often this is because a hardware decision was made since the number of services with a minority language doesn't make it sensible to pay for a display which can actually present that language where the hardware is limited). The majority of solutions may also be searching content using English words – and providing English versions of the descriptions may help your 'findability' in search engines. In summary - even if your default language would be non-English you should consider having an English version of your description.

Best practice recommendation: the minimum requirement is to provide at least a short description. However you should understand that also providing long (and extended) descriptions provides more information for a solution, which may use this information to allow 'findability' of your services by the audience.

From the example above this could appear in your xml like this – a simple example with just a short and long descriptions all in English (Great Britain):

Another example – demonstrating French and English versions of short and long descriptions:

[organisation|brands/brand]/links

see parent document advice for node requirement, child requirements advice can be found belowThis node allows an organisation to provide links to their own internet accessible services for the root organisation or their organisation's brands – for example a link to their home page on the web, or perhaps their mobile website.

Links is not a required node, but if you have a links node you must have at least one link child.

As a child node – link requires that you provide all attributes – devicetype, mimetype and url.

An example of a links node is:

The devicetype and mimetype attributes are a way of signaling the appropriateness of the linked to content in the url attribute.

.../links/link@devicetype

attribute is requiredThe value of devicetype should be specified using any of the media-types listed in W3C's Cascading Style Sheet specification.

Media-types are worth thinking about in terms of how appropriate it would be to present this to your user/audience – so we are talking about User Interface Engineering. If you think about this in terms of the rough distance from the user's eyes to the interface you establish the following rule of thumb: television is a '10 foot' experience because 10 feet (about 3meters) is an average of how far a person sits distant to their television; a mobile phone would be a '1 foot' experience (basically - personal - up close); someone using a computer is about a '3 foot' experience (laptop or desktop... it's probably about 3 feet away from the user, possibly 2 feet... but this is just a guide); and a cinema or projector would be more than 10 feet away so we'll call that '10+ foot' experience.

Therefore valid values of devicetype are:

.../links/link@mimetype

attribute is requiredHere you specify the content type that will be returned should you visit the url specified. e.g. text/html, text/vnd.vap.wml

IANA maintains a list of commonly used mime-types - though it is not exhaustive and we do not place a restriction on the types that can be referenced.

[organisation|brands/brand]/tags

see parent document advice for node requirement, child requirements advice can be found belowThe ability to provide free-text 'tags' allows the organisation to provide some useful keywords that describe itself or the brands that it provides. Tags is an optional node.

.../tags/tag

node is required, 1 or moreThe children of the tags node are tag nodes and you can provide as many as you like. The text node of each tag node should contain a string that constitutes a word or short phrase. The concept of 'tagging' something is to allow search functions to allow some categorisation and grouping based on free-text.

Tagging should be considered in conjunction with the genres node – which is a more restricted way of categorising by using common shared vocabularies. Consider correctly categorising by using the genres node as much as you can, and where you have things that don't fit – use tags.

Tags can also be used to provide alternative spellings or common miss-spellings of an organisations name.

.../tags/tag@weight

attribute is optionalIn order to suggest hierarchy or importance of tags, you can use the weight attribute of the tag node. The value of this attribute should be an integer signifying the relative 'weight' of this tag in relation to other tags.

The lowest weight is zero. Any node that has a higher weight than zero should be considered as having higher importance.

If no weight is specified on any tag then everything is of equal weight. If only some tag nodes have a weight specified, then any tag nodes without a weight should be considered having a weight of zero. Tag nodes with the same weight should be considered as having equal weight.

How a solution interprets the weight given by an organisation to any tag, and the relationship between that tag and others, is up to the solution. It is not something that the IMDA wishes to specify – as all solutions have their own methods for determining how to search or browse information. The concept of weight is merely to provide assistance to highlight how important the organisation believes a tag is to them.

[organisation|brands/brand]/genres

see parent document advice for node requirement, child requirements advice can be found belowCategorise your organisation or brands by providing genres that describe them. Genres is an optional node.

Tip: Genres supplied by the you (the organisation) are used by the solution to determine where your brands appear in the solution. However – solutions may not use these verbatim to list your brands, as the genres may not match with their solution – so consider anything you provide here as advice about your brands.

Genres can contain entries which are either:

unconstrained

if you have your own concept of how your content should be categorised into genres

constrained

by constraining your genre types to previously published shared vocabularies (e.g. TV-Anytime, iTunes, Media-RSS, EBU...) you can assist solutions to being able to categorise your content alongside content from other organisations.

What is a 'shared vocabulary'? Often referred to as a 'controlled vocabulary'. A vocabulary is a set of terms you are familiar with - a controlled vocabulary is one agreed by a group that allows them to talk about things and know that what one person means when they use a term is the same as what another person means with the same term.

"Controlled vocabulary schemes mandate the use of predefined, authorised terms that have been pre-selected by the designer of the vocabulary, in contrast to natural language vocabularies, where there is no restriction on the vocabulary." - Wikipedia

We call a controlled vocabulary a 'shared' vocabulary merely because agreed terminology is 'shared' within a group. The two terms are interchangeable.

The genres node contains definitions about which shared vocabulary you wish to use (and you can use multiple if you wish), alongside the actual genre identification.

You can mix constrained and unconstrained genres, or have only constrained or unconstrained genres – which, in summary means, that you can have either:

1. constrained only
2. unconstrained only
3. a mixture of constrained and unconstrained

Best practice guidance: it is recommended strongly by the IMDA that you do not provide unconstrained only as this limits the solution from being able to provide your content listed against other content from other organisations. It also makes it difficult to search for – especially if your genres are very different from the shared vocabularies (see next section about domains and further notes for broadcasters). We recommend strongly that you provide constrained only or both.

Language: most common shared vocabularies use English language terms. This is because of the majority of solutions current in service. Should you have non-English genres - please consider mapping these to a shared vocabulary (see domains below) and where not possible, providing them unconstrained. A future version of this specification may add language support to this node. (Please provide feedback if you desire this feature)

.../genres/genre

node is required, 1 or moreThe children of genres are genre nodes. You can specify 1 or more genre nodes. If you haven't provided the genres node then you don't have any genre nodes.

Here's a quick example – this shows 6 constrained genre nodes and 1 unconstrained genre node:

genre nodes come in two flavours – so that you can provide constrained or unconstrained genres:

Unconstrained genre node

The text node of genre node is not constrained – so you can put whatever your genre reference is. This could be a text string representing the genre itself, or a numeric reference to some vocabulary you use.

Here are some examples of unconstrained genre nodes:

Please consider providing feedback to us about your vocabulary, and why other shared vocabularies cannot provide what you need – this may allow us both to consider making your vocabulary a shared one, and adding it to this spec.

Constrained genre node

The text node of a genre node should contain a reference to the genre as specified in a shared vocabulary and is therefore 'constrained'. We define which shared vocabulary we are using by specifying a genre@vocabulary attribute. Here are a few example constrained genre nodes:

In this example we have used a few of our vocabulary attribute values, the full list is in the table below, and are a short string that identifies a particular shared vocabulary (and the version referred to).

We recommend that you use, at a minimum, the TV-Anytime genre list.

Don't see your favourite genre shared vocabulary above? Please contact us and ask us to consider it for inclusion – you'll need to explain why other shared vocabularies cannot provide what you need – this may allow us both to consider making your vocabulary a shared one, and adding it to this spec.

[organisation|brands/brand]/logos

see parent document advice for node requirement, child requirements advice can be found belowThis node allows an organisation to provide various logo assets – graphic imagery – related to the organisation or the organisation's brands. This is so that a solution can provide the correct branding. Since there are a potential infinite number of possible solutions that could use different sizes and formats, we specify here a range of assets that you should provide based on common solutions currently in the industry.

Logos is a required node. You can specify multiple different sizes or formats of logos by using the child logo node.

As a child node – logo requires that you provide at least attributes – type and url. The width and height are needed when the image type is a bitmap image. The background attribute is optional – and is used to signal the background colour that is appropriate for the logo provided – this allows you to produce multiple logo nodes for the same type, but that would be appropriate for certain background colours.

An example of a logos node is:

.../logos/logo@type

attribute is requiredThe logo@type attribute allows us to identify some standard image profiles which would allow a solution to pick the closest image dimensions and type for their solution. There is also an 'unrestricted' profile that allows you to list any assets you may have that you think could be useful. The list of available profiles is as follows:

Some frequently asked questions about these profiles are available in Appendix: Frequently Asked Questions.

These are the initial set of logo types as researched by the IMDA based on review of existing specifications on multiple devices and discussion around minimising these to some key size and format profiles. However – should you find that we've missed something or simply got something wrong, please don't hesitate to provide feedback.

.../logos/logo@url

attribute is requiredThis is the Uniform Resource Locator (URL) to the image asset – it should be an absolute fully qualified URL that is publicly available. Organisation's images should be available via HTTP protocol, and publicly available.

Some tips for the aggregator: your solution shouldn't rely on calling images directly off the organisation's web server it is always preferable for your solution to cache the logo on your local servers, this obviously is required if your solution requires to process a logo and cache it at a different size, colour depth or graphic format (gif, jpeg,...).

.../logos/logo@background

attribute is optionalThe background attribute is an optional attribute. This attribute allows you, as a media organisation, to signal to the aggregator of your data whether a logo is appropriate to be displayed on a particular background. If you do not specify this attribute, the aggregator should assume this means that the logo in this node can be used on any background. If described colour is not available on target solution, then solution will choose closest available colour. The values for background are taken from the W3C's Cascading Style Sheets 2.1 (r1) specification, though we currently limit these to black, silver, gray and white.

Why would you need to provide this attribute? Well, consider the following diagram. Each row represents one particular logo variant, with the columns showing a different background colour in use (the variant on the far right shows a hatched pattern as a background to show which bits of the logo are transparent). Disclaimer – these mock-ups do not necessarily follow brand useage guideines from the owners of the logos, and are merely used here to illustrate the issue.

Probably the most obvious from this is when you have the BBC logo on a black background, or the reversed BBC logo on a white background – I hope you'll agree that this is a problem. So, in order to address this – the background attribute is available so that you can provide several logo nodes for one type. Also – we picked four colours for background as these are probably the most common, although in the diagram above we have only used three due to space.

Note that you can have only one logo node per background colour, and that you may have one logo node that doesn't specify background – this would be the default logo to use, and any others specified would override that logo based on the background colour. So, for example, the BBC could specify 3 logo nodes (for one type) for the logo of their 'Media Organisation' – one would have no background attribute and would link to the third BBC variant (on the diagram above - black lettering on white blocks surrounded by black lines), another node would link to the second BBC variant (black letters on white blocks) with a background value of black, another node would link to the first BBC variant (white letters on black blocks) with a background value of white.

XML Schemas

Schemas are not available as yet – we have draft schemas available but are waiting on feedback regarding this version of the specification before finalising.

Example documents

The example xml documents for each of the main areas used in this specification can be downloaded here:

• Root: imda.xml
• Organisation: imda_org.xml
• Brands: imda_brands.xml
• Transports: imda_transports.xml
• Manifests: imda_manifests.xml

We also have a set of these documents which contain only the minimum metadata required. Please note that these only contain space for a very simple media organisation that has one brand and only one transport for that brand. We aim to make available, via the IMDA website, a straightforward form-based wizard that allows you to create these xml documents for very simple media organisations.

• Minimum Root: imda.xml
• Minimum Organisation: imda_org.xml
• Minimum Brands: imda_brands.xml
• Minimum Transports: imda_transports.xml

 

Frequently Asked Questions

General issues:

Why did you decided to use XML documents to share metadata in this way?

XML documents are commonly used for sharing structured data, it also allows for zero-resource for smaller organisations with minimum data sets that are manually produced.

Why have you chosen your XML document to use UTF-8 language encoding?

See "Why UTF-8?" for an answer to this.

You could have put everything in the one XML document, why have you split it up into multiple documents?

See "Why split data into multiple XML documents?" for an answer to this.

Issues relating to Logos (see the shared node information on Logos):

Why are the bitmap types all Portable Network Graphics (PNG) format?

Graphics Interchange Format (GIF) and Joint Pictures Expert Group (JPEG) are common, however in order to support all everything they can represent plus including alpha channels properly, the use of PNG is required. Remember - this is what the organisation provides, even if a solution resizes/resamples/transcodes this to another format for their needs. There is a useful comparison of common image types to PNG available on Wikipedia.

Why bother to provide the Scalable Vector Graphics (SVG) types?

If your logos can be described as an SVG, then you should consider providing these as the solution could scale these to whatever size they require, with no loss of quality of image – the solution could then cache them as any format of image they wish that's supported in their solution. Unlike with the bitmap formats, where scaling will have an impact on the quality of the resulting image.

What about file size?

Clearly the idea here is to have a balance of best quality and file size – it may well be the case that a solution picks the nearest to it's needs and then resizes/resamples/transcodes this to another format. If you are providing an SVG type then you can provide a link to either the uncompressed .svg or the gzipped-compressed .svgz

Why have you specified these colour bit-depths?

These are guidelines about the colour support of some solutions. However - all solutions vary on their support based on the type and abilities of the display they use. Therefore the solution may choose to resample your logos into a colour palette that works with the output device they are using.

Should I be worried about 'tv-safe' colour palettes?

it was important to make sure for Cathode Ray Tube (CRT) based televisions and displays to make sure that the colour palette of any image to be displayed on these were limited to avoid colour bleeding across scan lines. This was only a small number of RGB colours that were too bright, and common image editing software (e.g. Photoshop) has a filter for these. Note that extremes like white and black were avoided by limiting them to a light grey (RGB - 240, 240, 240) and a dark grey (RGB - 16, 16, 16). However - on HDTVs (LCD and LED based screens) it seems less likely that this sort of problem would persist. We currently do not have enough information regarding this area – if you have any information on this, please do get in touch. Therefore, at this time, we don't require you to use a tv-safe colour palette for your larger images. Should you already have 'tv-safe' images in these sizes, then this is ok.

Issues relating to Geographical reference systems in relation to our locations nodes:

Can GeoRSS polygons define a polygon passing the +180/-180 longitude (International Date Line)?

The specification of GeoRSS does not explicitly state that a polygon can cross this border, but an example is given of a polygon (drawn as rectangle) crossing this border.

Can GeoRSS polygons define polygons with a hole in them?

No, but using the reference type of location you could specify one polygon location, then another, then use the reference grouping type to 'exclude' (i.e. subtract) one polygon from another.

Is there any ambiguity in the GeoRSS specification?

Yes, we think so. It seems that GeoRSS polygons have a restriction: given two random distinct coordinate pairs in a polygon, neither their latitudes nor their longitudes may be separated by more than 179 degrees. If they would span more than 179 degrees, then the definition becomes ambiguous about which way they should wrap around the earth. This implies that a single polygon cannot cover more than appr. 50% of the earth – a work around is to group polygon locations together to create an area that covers more than 50%, but individually don't account from 50% or more. However, we feel that this issue is probably unlikely to be a problem for most, if you have an issue with this please do provide us with feedback.

Why GeoRSS, there are plenty of other Geographical reference systems?

We took a look at some of the common reference systems out there: including OpenGIS and GML as well as GeoRSS (Simple). We currently feel that the simplicity of GeoRSS (Simple) is suitable for the specification in those present in the discussions. If you find you are unable to represent locations using the methods provided then we ask you to provide feedback.

Do you have a question we don't have an answer for in this document? We'd love to hear from you – help us make things better by providing feedback.

© Internet Media Device Alliance