1. FIMS v1.1 Version numbers in schema Richard Cartwright Quantel July 2013

2. Always a client and server … Combinations – 1.1 orchestrator requests to 1.0.7 service – 1.0.7 service responds to 1.1 orchestrator – Or 1.2 and 1.1, or 1.2 and 1.0.7 – … and for notifications, clients become servers, servers become Requirements – A family of "backwards compatible" clients and servers where the major version number is the same. – Major version number only changes on big changes: e.g. Move from XML to JSON Fundamental change to data model – Avoid the web browser implementation headache (all HTML versions) while making interoperability OK for users Is it possible?

3. Likely changes Attributes – adding – older versions should ignore ##other – means new attribute is an error – removing – unlikely – changing type – ignore enumerations you don't know? Complex types and elements – Adding – preferably at the end of a sequence – older ignores ##other – means new elements are an error – Removing – unlikely – changing type – changing cardinality – maxOccurs = 1 to unbounded (just a couple of minOccurs = 1 to 0 in capture service) WSDL/SOAP: XML change REST: XML or headers

4. Forgiving reader, compliant writer XML schema under- and over- constrains – Under: Difference between request, response – Over: Sequences – Validate during development? or at runtime? Auto-generation frameworks – Don't automatically deal with multiple versions – Needs mitigation – unexpected cost XML parser without schema – Can be built to be more forgiving Implementation guidelines section

5. Labeling the versions Enable analyzers and tools to be more or less forgiving Extreme: AAF requires meta model to be embedded ✗ Choice of representation – Add elements or attributes to resource, fault, … etc.. Don't confuse FIMS version with resource revision SMPTE approach within MXF (e.g. major = 1, minor = 3) – Encode in the namespace E.g. http://base.fims.tv/1.1 SMPTE approach to XML schemas Choice of location – Add to the resource ref & fault type => notifications Everything data rather than message mechanics – Add to messages (WSDL-SOAP) and headers (REST)

6. Examples POST.../api/job <bms:job xsi:type="tran:TransferJobType" xmlns:tran="http://transfermedia.fims.tv" xmlns:base="http://base.fims.tv" xmlns:xsi="http://www.w3.org/2001/ XMLSchema-instance" version="1.1"> 101… low … Or version="1.1" ✓ Or add tertiary="7" for 1.0.7

7. Version check API Do we need an API – Servers and clients can check before messages – Central repo of systems and version numbers

8. Discussion Version numbers as attributes or in the namespace? – Attribute Mandatory or optional? How to deal with 1.0.7? – Mandatory from 1.1 onwards – No attribute = 1.0.7 Version attribute location – Resources, faults, messages (…request, …response), headers – Proposal yesterday: put at both resource and message levels – What about mixed mode messages? – Alternative: Force client and server to use same version, then only at the message level? – Create mapping … document the delta – Different endpoints, one per version – use redirection – Fault message … but what about the legacy? Do we need a version on fault at all? – Send a 1.1 message to 1.0.7, it will fault? – Orchestration is configured with locations – Agreed proposal: One endpoint per version – should reject messages of the wrong version SOAP: Version numbers in request messages SOAP: Responses also have a message, shall match request Faults – no version number SOAP: Notifications – version number, shall match initial request and response SOAP: Events – Match the version of the endpoint RCR is a good place to put version information and version check API – get versions returns all known endpoints with their versions – please can the repository group add this soon? REST: All HTTP requests and responses have header property: X-FIMS-Version REST: Events need to carry version details

9. Agreed Proposal – One endpoint per version – should reject messages of the wrong version SOAP: Version numbers in request messages SOAP: Responses also have a message, shall match request Faults – no version number SOAP: Notifications – version number, shall match initial request and response SOAP: Events – Match the version of the endpoint RCR is a good place to put version information and version check API – get versions returns all known endpoints with their versions – please can the repository group add this soon? REST: All HTTP requests and responses have header property: X- FIMS-Version REST: Events need to carry version details

10. Actions Add version attributes to 1.1 schemas – RIC/Ash Create new fault type: SVC_S00_0019 – Version mismatch. – RIC/Ash - Done REST … add new header - RIC Text in part 1 document to describe - RIC Implementation guidelines - All – Translation service