Model Resource Naming

Unlike general web architecture, ERMrest expects clients to understand the URL internal structure and permits (or even encourages) reflection on URL content to understand how one resource name relates to another. To support introspection and management, the data model of a catalog is exposed as a set of model-level resources. These model elements also influence the naming of data resources.

Catalog Names

The ERMrest model resources belong to a catalog resource:

• service /catalog/ cid [ @ revision ]

where the components of this root path are:

• service: the ERMrest service endpoint such as https://www.example.com/ermrest.
• cid: the catalog identifier for one dataset such as 42.
• revision: (optional) timestamp identifying a historical snapshot of the catalog.

The catalog resource has a representation which provides basic information about it including access control lists.

In general, the optional @ revision modifier allows reference and read-only retrieval of historical resource representations. Only the latest, live catalog represented by cid without a revision supports mutation.

Catalog Aliases

Through an optional alias-management interface, the administrator can bind (or re-bind) additional identifiers for a catalog:

• service /alias/ alias

where the components of this management path are:

• service: the ERMrest service endpoint such as https://www.example.com/ermrest.
• alias: the additional catalog identifier for one dataset such as 42 or production.

The catalog alias has a representation which provides basic management state information about the binding of alias to a storage catalog cid and an alias ownership access control list.

When an alias is bound to a live catalog, it also implicitly exists in the catalog resource space:

• service /catalog/ alias [ @ revision ]

where it has a representation mostly based on the bound storage catalog. However, certain lifecycle states can result in alias only existing in the alias/ management space while not appearing in the catalog/ access space, i.e. when the alias does not currently resolve to an accessible catalog.

Generic Model Sub-Resources

A number of different resource types in the model hierarchy all support sub-resources with very similar interfaces. Rather than describing each sub-resource independently, we summarize them here.

Annotations

Annotations are reified as sub-resources:

• subject /annotation/ annotation key

Subject Kind	Purpose
catalog	Annotations about whole catalog
schema	Annotations about one named schema
table	Annotations about one named table
column	Annotations about one named column
key	Annotations about one key constraint
foreign key	Annotations about one foreign key constraint

Each keyed annotation has a simple representation which is a machine-readable document in application/json format. The expected content and interpretation of the JSON document is externally defined and associated with the annotation key which SHOULD be a URL (escaped with standard URL-encoding before embedding in this annotation name URL). The purpose of the annotation key is to allow different user communities to organize their own annotation standards without ambiguity.

Additionally, a composite resource summarizes all existing annotations on one annotated resource, for convenient discovery and bulk retrieval:

• annotated resource /annotation
• annotated resource /annotation/

Comments

Comments are reified as a sub-resources:

• subject /comment

Subject Kind	Purpose
schema	Comment about one named schema
table	Comment about one named table
column	Comment about one named column
key	Comment about one key constraint
foreign key	Comment about one foreign key constraint

This resource has a simple representation which is just human readable text in text/plain format.

ACLs

Access control lists (ACLs) are reified as sub-resources:

• subject /acl/ acl name

Subject Kind	Purpose
catalog	ACLs granting access to whole catalog
schema	ACLs granting access to one named schema
table	ACLs granting access to one named table
column	ACLs granting access to one named column
foreign key	ACLs granting access to one foreign key constraint

Each keyed ACL has a simple representation which is a machine-readable array of authorized client attribute strings or a null value in application/json format.

ACL Bindings

Dynamic access control list bindings (ACL bindings) are reified as sub-resources:

• subject /acl_binding/ binding name

Subject Kind	Purpose
table	ACL bindings granting access to one named table
column	ACL bindings granting access to one named column
foreign key	ACL bindings granting access to one foreign key constraint

Each keyed ACL binding has a simple representation which is a machine-readable object or a false value in application/json format.

Model Names

The ERMrest model resources are named under a root collection of schemata for a particular catalog:

• service /catalog/ cid [ @ revision ] /schema/

where the components of this root path are:

• service: the ERMrest service endpoint such as https://www.example.com/ermrest.
• cid: the catalog identifier for one dataset such as 42.
• revision: (optional) timestamp identifying a historical snapshot of the catalog schemata.

This root schemata resource has a representation which summarizes the entire data model of the catalog as a single document.

Schema Names

Each schema or namespace of tables in a particular catalog is reified as a model-level resource:

• service /catalog/ cid [ @ revision ] /schema/ schema name

This named schema resource has a representation which summarizes the data model of all tables qualified by the schema name namespace.

Table Names

Each table is reified as a model-level resource:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name

This named table resource has a representation which summarizes its data model including columns, keys, and foreign keys. Within data resource names, a table may be referenced by table name only if that name is unique within the catalog or by a fully qualified schema name : table name. Concrete examples of such names might be table1 or schema1:table1.

Column Names

Each column is reified as a model-level resource:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /column/ column name

This named column resource has a representation which summarizes its data model including name and type. Within data resource names, a column may be referenced by:

• column name when resolving within an implicit table context;
• table alias : column name when resolving against a context where table alias has been bound as an alias to a specific table instance;
• table name : column name when resolving against the model and table name is unique within the catalog;
• schema name : table name : column name when resolving against the model and table name might otherwise be ambiguous.

Key Names

Each (composite) key constraint is reified as a model-level resource:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /key/ column name , …

This named constraint has a representation which summarizes its set of constituent key columns. The meaning of a key constraint is that the combination of listed columns must be a unique identifier for rows in the table, i.e. no two rows can share the same combination of values for those columns.

ERMrest also supports pseudo-keys on views, which allow the uniqueness properties of views to be asserted both for clients introspecting the catalog model and for ERMrest itself to reason about queries on the view. Psuedo-keys are chosen automatically when an authorized client creates a key constraint on a view, while real database constraints are used when the client creates a key constraint on a table.

• NOTE pseudo-keys are advisory, not enforced in the database, and not validated by ERMrest. A client SHOULD NOT assert inaccurate psuedo-key constraints as it could mislead other clients who introspect the schema or lead to unexpected query results as ERMrest formulates relational queries assuming the constraints are true.
• Future ERMrest releases MAY enforce validation on psuedo-keys so clients SHOULD NOT depend on the ability to create inaccurate psuedo-constraints.

Additionally, a composite resource summarizes all existing key constraints on one table for convenient discovery and bulk retrieval:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /key
• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /key/

Foreign Key Names

Each (composite) foreign key constraint is reified as a model-level resource:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey/ column name , … /reference/ table reference / key column , …

This named constraint has a representation which summarizes its set of constituent foreign key columns, another referenced table, and the set of key columns that form the composite key being referenced in that other table, including the mapping of each foreign key column name to each composite key key column. The table reference can be a qualified table name, e.g. schema1:table1 or an unqualified table name, e.g. table1. The meaning of this constraint is that each combination of non-NULL values in schema name:table name MUST reference an existing combination of values forming a composite key for a row in table reference.

ERMrest also supports pseudo-foreign keys on views, which allow the reference links of views to be asserted both for clients introspecting the catalog model and for ERMrest itself to reason about queries on the view. Psuedo-foreign keys are chosen automatically when an authorized client creates a foreign key constraint on a view or referencing a view, while real database constraints are used when the client creates a foreign key constraint on a table referencing another table.

• NOTE pseudo-foreign keys are advisory, not enforced in the database, and not validated by ERMrest. A client SHOULD NOT assert inaccurate psuedo-foreign key constraints as it could mislead other clients who introspect the schema or lead to unexpected query results as ERMrest formulates relational queries assuming the constraints are true.
• Future ERMrest releases MAY enforce validation on psuedo-foreign keys so clients SHOULD NOT depend on the ability to create inaccurate psuedo-constraints.

Additionally, a composite resource summarizes all foreign key constraints on one table for discovery and bulk retrieval purposes:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey
• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey/

Additionally, a composite resource summarizes all foreign key constraints involving one composite foreign key column name list:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey/ column name , …
• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey/ column name , … /reference
• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey/ column name , … /reference/

Finally, a composite resource summarizes all foreign key constraints involving one composite foreign key column name list and one table reference:

• service /catalog/ cid [ @ revision ] /schema/ schema name /table/ table name /foreignkey/ column name , … /reference/ table reference

(While highly unusual, it is possible to express more than one foreign key constraint from the same composite foreign key column name list to different composite key key column lists in the same or different table reference tables.)