API documentation - described affiliation doesn't match observed metadata

[adam-rehin]

Documentation of affiliation: https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md#affiliation describes ONLY the 'name' field.

However, I have observed more complex results - for example (for 'DOI': '10.14232/ejqtde.2022.1.14'):

            'affiliation': [{
                    'name': 'Changsha University of Science and Technology'
                }, {
                    'id': [{
                            'id': 'https://ror.org/03yph8055',
                            'id-type': 'ROR',
                            'asserted-by': 'publisher'
                        }
                    ],
                    'department': ['School of Mathematics and Statistics']
                }, {
                    'name': 'Hunan Provincial Key Laboratory of Mathematical Modeling and Analysis in Engineering',
                    'place': ['Changsha, Hunan,   P. R. China']
                }
            ]

One thing I've noticed (from a relatively small result set) is that the 'id' array always seems to be provided in a separate object; however it would be more useful if it could be provided within the same object as the 'name' that it is related to, the same applies to the 'department' and other fields. In this way there would be a single object per affiliation - which would assist in handling true multiple affiliations (i.e. where an author is associated with more than 1 institution).

Please can the documentation be updated to reflect all possible fields in the affiliation object, including a definition of what each field contains.

It would be particularly helpful to understand any relationship between your affiliation data-model and the JATS XML schema, which can provide the granularity of information shown below in a JSON representation of relevant JATS XML elements https://jats.nlm.nih.gov/publishing/tag-library/1.3/element/aff.html:

                   /** JSON representation of JATS <aff> XML structure **/
                    "affiliations": [ {
                        "identifier" : [{
                            "type" : "<institution-id institution-id-type='ROR'>",
                            "id" : "<institution-id institution-id-type='ROR'>id-value"
                        }],
                        "org": "<institution> ",
                        "dept": "<institution  content-type='dept'>",
                        "street": ["<addr-line>"],
                        "city": "<city>",
                        "state": "<state>",
                        "postcode": "<postal-code>",
                        "country": "<country>",
                        "country_code": "<country country="EN">"
                        }]