Decision on further steps for Metadata documentation

[Rainer Hoerbe <rainer@hoerbe.at>]

I would like to summarize the status of the agenda item "Conceptual Overview of Metadata" and ask for decisions on further steps:
 
My starting point was: "SAML Technical Overview does explain major use cases and protocol sequences quite well, but does not such a good job in helping to understand data structures, in particular metadata, very well. I would like to see the structural model of SAML being described using UML. That should at least be more readable than XSD and consolidate the various extensions to metadata."
 
Problem: SAML V2.0 documents make it difficult to get introduced to metadata for several reasons:
·       The specification is spread over several documents;
·       XSD as a language and extensive use of inheritance and other constructs address implementers but add a layer of complexity for other readers;
·       Simple questions like what are the entities in the model, their properties and relationships are not easy to answer.
·       Semantic information is spares in several areas, or to be found at the shibboleth wiki.
 
There were two drafts proposed to provide an overview the SAML MD:
 
First, a conceptual model in UML that is just one level of granularity above the XSD sepc:
http://www.aboutidentity.org/sites/www.aboutidentity.org/static/consolidated-saml-md-schema-uml.pdf.
The UML-notation was not so much welcomed.
 
Second, a significantly reduced description from March 2013. It describes just the entities, but not attributes, relationships or in which document/schema an entity is specified:
http://files.hoerbe.at/daunlod/eadocx-quickdoc.pdf
 
These drafts are not mutually exclusive, for example a further reduced UML diagram could be added to the second document to provide a more visual overview to those who prefer this kind of notation. Or additional information could be added as text in tables.
 
For further steps a few points should be decided in the SSTC:
- Is the technical overview the right place to insert this documentation?
- Which parts of both documents should be used?
- What level of detail is appropriate for this documentation?
 
As a side note: Is there a pressing reason to have the Entity Category spec (draft-macedir-entity-category-00) at the IETF? For achieving a consolidated picture of MD an OASIS document might be easier to manage.
 

- Rainer