deriva-annotation-config

Using deriva-annotation-config to configure annotations

The deriva-annotation-config utility reads a configuration file and uses it to set annotationss for an ermrest catalog (or for a schema or table within that catalog). Usage is:

deriva-annotation-config [-n|--dryrun] [-v|--verbose] [-s|--schema schema] [-t|--table table] [--host host] [--config-file config_file] [--credential-file credential_file] catalog

where the required arguments are:

catalog: an ermrest catalog number (e.g., 1)

--config_file file: the name of a configuration file

Options are:

-credential_file file: read credentials from the named file (if not specified, look for credentials maintained by deriva-auth)

--dryrun: do nothing, just print out the catalog schema that would be applied

--verbose: verbose, print acls and acl bindings for each object

--schema schema: operate only on the named schema, not the whole catalog

--table table: operate only on the named table, not the whole catalog (requires the --schema option)

--host host: configure the server on the specified host (default localhost)

Config file format

The config file is a JSON file divided into the following stanzas:

known_attributes: Attributes (i.e., annotation URIs, such as tag:isrd.isi.edu,2016:display) managed through this config file

schema_annotations: Catalog-level annotations.

schema_annotations: Annotations for individual schemas.

table_annotations: Annotations for individual tables.

column_annotations: Annotations for individual columns.

foreign_key_annotations: Annotations for foreign keys.

The known_attributes stanza

This stanza contains parameters that control the behavior of deriva-annotation-config itself. This section has three sub-sections: managed, ignored, and ignore_all_unmanaged.

The managed section is a list of annotation types managed by deriva-annotation-config.

The ignore_all_unmanaged section is a boolean: if true, deriva-annotation-config will leave any annotations not in the managed list unchanged. If false, deriva-annotation-config will clear any annotations not in the managed list.

The ignored section is a list of annotation types that are recognized by deriva-annotation-config but that aren’t created or updated by it, depending on the value of ignore_all_unmanaged. If ignore_all_unmanaged is true, the program leaves existing annotations of this type alone. If ignore_all_unmanaged is false, the program removes existing annotation sof this type.

Example:

    "known_attributes": {
        "ignore_all_unmanaged": false,
        "managed": [
            "tag:isrd.isi.edu,2016:column-display", 
            "tag:isrd.isi.edu,2016:display", 
            "tag:isrd.isi.edu,2016:foreign-key", 
            ...
    ],
    "ignored" : [
            "comment", 
            "description", 
            "facetOrder"
    ]
    }

This is a version one might use to remove all comment, description, and facetOrder annotations from a catalog. If ignore_all_attributes were true, those annotations would be left unchanged.

The schema_annotations stanza

This is where annotations for schemas are set. The syntax is a list of entries of the form:

{schema_descriptor: value, annotation_descriptor: value}

A schema_descriptor is either:

"schema": schema_name

or

"schema_pattern:" regular_expression

When setting permissions on a schema:

  • if an exact schema match is found, the associated ACL is used (and any matching schema_pattern entries are ignored).
  • If no exact schema match is found and exactly one matching schema_pattern entry is found, then that ACL is used.
  • If no exact schema match is found and more than one matching schema_pattern entry is found, then an error is thrown.

An annotation_descriptor has the form:

"uri": annotation_uri "value":: annotation_value

For example:

        {
            "schema": "Vocabulary", 
            "uri": "tag:misd.isi.edu,2015:display", 
            "value": {
                "name_style": {
                    "title_case": true, 
                    "underline_space": true
                }
            }
        }

The table_annotations stanza

This is where annotationss for tables are set. The syntax is a list of entries of the form: {schema_descriptor, table_descriptor, annotation_desciptor} The schema_descriptor and annotation_descriptor have the same form as above.

A table_descriptor is either:

"table": table_name

or

"table_pattern:" regular_expression

Regular expression matching is used:

  • If an entry with an exact schema and table match is found, the associated ACL is used (and any other matching entries are ignored).
  • Otherwise, if entry with an exact schema match and exactly one table_pattern match is found, that ACL is used.
  • Otherwise, if exactly one entry with a schema_pattern and table_pattern match is found, that ACL is used.
  • If none of the above is true, and multiple matching entries are found, then an error is thrown.

For example:

    "table_annotations": [
        {
            "schema": "Vocabulary", 
            "table_pattern": ".*_terms", 
            "uri": "tag:isrd.isi.edu,2016:table-display", 
            "value": {
                "row_name": {
                    "row_markdown_pattern": "{{name}}"
                }
            }
        }

This sets an annotation for any table in the “Vocabulary” schema whose table name ends in “_terms”.

The column_annotations stanza

This is where ACLs for columns are set. The syntax is a list of entries of the form: {schema_descriptor, table_descriptor, column_descriptor, annotation_descriptor} The schema, table, and annotation descriptors have the same form as above. The column_descriptor is either:

"column": table_name

or

"column_pattern:" regular_expression

Regular expression matching is used:

  • If an entry with exact schema, table, and column matches is found, the associated ACL is used (and any other matching entries are ignored).
  • Otherwise, if exactly one entry is found with schema, table, and column matches is found, that ACL is used
  • If multiple regular-expression matches are found and no exact match is found, an exception is thrown.

Example:

        {
            "column": "RCT", 
            "schema_pattern": ".*", 
            "table_pattern": ".*", 
            "uri": "tag:misd.isi.edu,2015:display", 
            "value": {
                "name": "Creation Time"
            }
        }

This sets the display name for any column named “RCT” in the catalog.

The foreign_key_annotations stanza

This is where annotations for foreign keys are set. The syntax is a list of entries of the form:

{schema_descriptor, table_descriptor, fkey_schema_descriptor, fkey_name_descriptor, annotation_descriptor}

The schema, table, and annotation descriptors have the same form as above. The fkey_schema_descriptor is either:

"foreign_key_schema": foreign_key_schema_name

or

"foreign_key_schema_pattern": regular_expression

The fkey_name_descriptor is either:

"foreign_key": foreign_key_name

or

"foreign_key_pattern": regular_expression

These specify the foreign key schema and name. As with the column_acls stanza:

  • If an exact match is found, it’s used
  • If no exact match is found and exactly one regular expression match is found, it’s used.
  • If no exact match is found and more than one regular expression match is found, an error is thrown.

Example:

        {
            "foreign_key": "Antibody_Gene_Association_NCBI_GeneID_fkey", 
            "foreign_key_schema": "", 
            "schema": "Antibody", 
            "table": "Antibody_Gene_Association", 
            "uri": "tag:isrd.isi.edu,2016:foreign-key", 
            "value": {
                "to_name": "Related Genes"
            }
        }