Resource Description (Ontology/Schema) Versus Resource Layout (API)

Resource description refers to defining concepts and relationships that represent the content and structure of some subject matter (ontology) or a database (schema) in a formal language. The relationship between ontology and database schema is nuanced – Uschold provides a nice comparison.¹ You can formally describe resources using the resource description framework (RDF), SQL’s data definition language (DDL), etc.

Resource layout refers to the arrangement of resources and their relationships for a particular resource-oriented API.² The layout isn’t intrinsic – it refers to choices regarding what to “lay out”.

Not every conceptual resource needs to “graduate” to be an API resource – some may end their journey at the point of becoming only in-lined data types of other resources (Do you need to atomically interact with a concept?). Hierarchical relationships (i.e. containment/ownership) may make sense when there are cascading actions or inherited access policy / properties.

Resource layout, as a layer on top of resource description, is an opportunity to make the common case awesome – without compromising the feasibility of advanced cases – for a particular application.