When to use service vs extension vs seeAlso vs annotation?

[azaroth42]

Can we be more explicit in order to encourage consistency?

[azaroth42]

Proposal:

service is an endpoint that is intended to be interacted with by the client directly. Thus image, auth, search, ldn, and the W3C Annotation Protocol all fall into this category.

seeAlso is a machine readable external resource that is related to the current resource, but not necessarily describing it as per current definition. If it's necessary to be more precise about the relationship, then the external resource should provide that clarification with a link back to the appropriate resource.

Extensions are used for any inline JSON-LD based data associated with a resource, with an additional context at the top of the document. Geo-JSON and physical dimensions thus become extensions, and we will have an extensions annex that mirrors the services annex that list the known extension patterns.

Annotations are used just as they are today.

Content creator services were identified as not needing to be referenced from the presentation API documents, although their outputs would fall into the above categories. A community maintained list might be appropriate for this, but not an API annex.

[zimeon]

Note that other than clarifications, key change is move of geojson and phydim from services to extensions -- this is the key part to discuss in Toronto

[azaroth42]

This should probably subsume #1012 and #893. Propose to close those issues in favor of this one.

[tomcrane]

👍 to having this issue as the forum for all things related to the proposal above (#1269 (comment))

[zimeon]

👍 at Toronto WG meeting to go with proposal in #1269 (comment)