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"
}
}