Service Identification [v?.?.? BETA]

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. 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"

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

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 should always be at the root of the organisation's primary website to allow easy discovery of services. The file should be 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. Though this file is located in the root of the website, it's relatively short and merely acts like a sitemap of service. The actual service information can be stored anywhere that is more sensible, thus avoiding loading up the root file space of your server.

By locating this root document at a known location, as specified above, means that solutions can just quickly check if you already expose your data following our specifications – simply by looking for the document at the root of your webserver.

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.

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.

Although the imda.xml file should reside at the root of your web server, the locations of the other references can be anywhere else as long as they too are publicly accessible. This means that you don't need to 'clutter' the root of your web server. Also – some of the other services you have may logically reside elsewhere.

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.

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 two types of transport that are of use immediately to organisations and solutions:

In future versions of these specifications we will extend the transport types to other services – to allow you to provide simple links to other transports or bears which are not available via the public internet using IP. Please see "transport@type: the future" for more information.

We'll now look at these in detail.

transport@type : ip_direct

This should be considered as the primary transport type. We will use it 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 and in a number of recognised ways.

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 optionalThe physical availability 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 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. For example - the playlist. This should be publicly available on the internet. Example:

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

.../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.

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

This section of the specification is provided to demonstrate the types of transports we may add in the future – 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 should not rely on information being present or in a particular schema – this will likely change and coalesce into future Guideline's edition.

So - what other sort of transports might a solution be interested in? Well – since there is an infinite number of different types of solution potentially available on the market, limited only by the inventiveness and business models, we can assume that some solutions may cross the boundaries between only using public internet IP services and using other transports.

These, so-called, 'hybrid' solutions are already beginning to enter the market – solutions like Televisions that can tune terrestrial digital services (DVB-T) and have an internet connection also available; or Radios that have multiple traditional broadcast transports like Digital Audio Broadcasting (DAB) and FM but also have an internet connection to allow it to play back Internet Radio services. On these hybrid solutions we can imagine wanting, as an organisation, to provide links between the brand offering on different transports – this would potentially allow an audience member using an Internet-TV to be watching Sky News via DVB-T (possibly an HD variant) and then be able to augment their viewing by the solution that powers the Internet-TV to provide other services associated to Sky News; or someone listening to BBC World Service on an Hybrid-Radio via DVB-S in the USA but, when moving out of DVB-S coverage to only having an internet connection, the solution automatically offers to tune to the Internet stream of the BBC World Service.

Here is an example of how these sort of external transports could be presented:

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 – type, mimetype and url.

An example of a links node is:

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

.../links/link@type

attribute is requiredThe value of type 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 type 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 other attributes (width and height) are needed when the image type is a bitmap image.

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,...).

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

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 whole 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