search

linked-art / linked.art

Development of a specification for linked data in museums, using existing ontologies and frameworks to build usable, understandable APIs
https://linked.art/
Other
95 stars 15 forks source link

It would be helpful to have a table listing the model for references along with various contexts together in one place #465

Open beaudet opened 2 years ago

beaudet commented 2 years ago

It would be helpful if the specs could list a table enumerating cases when references are required to have an ID and when they are optional. For example, a reference to a Concept vs. a Dimension. It would also be helpful to differentiate between the URI forms that such IDs must take. For example, a reference can be 'internal' in the sense that it shares a base url pattern with the graph being validated, e.g. https://linked.art/example/object/0 or the URI could be external in some cases, e.g. to the AAT.

For example, if an art object is listed as a part of another object, the reference to the part can either be embedded data (no ID/URI) with a blank node that should (probably) only exist in the context of this particular object, OR the ID can be external (presumably), OR the ID can be internal which means it is defined elsewhere in another JSON file but exists in the graph as a referenceable entity.

I think the the specs for references say that only ID, _label, and type are permitted when the ID is present with some context-sensitive additions such as "identified_by" in the case of MeasurementUnit.

Another example: In the case of references to a Set, is the ID required or is it optional and are there different context-sensitive rules that exist when handling references to a Set? The examples show both ID included and absent. If a Set is defined locally, presumably it could either be embedded (in which case its use is limited to the entity where it's defined) or it can have a local URI.

It would be helpful for there to be a table in the API documentation where all of these permutations for references are visible together.

beaudet commented 2 years ago

clarification: asking for a consolidated table that looks across all the entities; Rob: "cross endpoint summary table"

azaroth42 commented 6 months ago

@beaudet I think this can be done by trawling the current API docs? Do you have time to work on it? Or (as it's not 1.0 critical) can we defer into 1.0.X as a useful editorial update?

beaudet commented 6 months ago

Don't have time currently. Ok pushing and agree on criticality. Helpful but certainly not required to release 1.0