Model representation for attribute/value field type

[martinjoconnor]

Model representation for attribute/value field type (metadatacenter/cedar-project#595).

[martinjoconnor]

[This message contains preliminary ideas and can be ignored. Skip to next message.]

Some initial notes.

The template representation of attribute-value fields can be pretty straightforward, e.g.,

  "My Attribute/Value": {
      "@type": "https://schema.metadatacenter.org/core/TemplateField",
      "@context": { ... },
      "type": "object",
      "title": "F1 field schema",
      "description": "F1 field schema autogenerated by the CEDAR Template Editor 1.5.0",
      "_ui": { "inputType": "attribute-value" },
      "_valueConstraints": { "requiredValue": false },
      "properties": {
        "@type": { ... },
        "@value": { "type": [ "string", "null" ] },
        "rdfs:label": { "type": [ "string", "null" ],
        "cedar:attributeFieldName": { "type": "string", "minLength": 1 }
        }
      },
      "required": [ "@value" ],
      "schema:name": "My Attribute/Value",
      "schema:description": "",
      "pav:createdOn": "2017-11-07T14:03:32-0800",
      "pav:createdBy": "https://metadatacenter.org/users/6e574d2d-8b29-48b2-b9f3-6ea463786c67",
      "pav:lastUpdatedOn": "2017-11-07T14:03:32-0800",
      "oslc:modifiedBy": "https://metadatacenter.org/users/6e574d2d-8b29-48b2-b9f3-6ea463786c67",
      "schema:schemaVersion": "1.3.0",
      "additionalProperties": false,
      "@id": "https://repo.staging.metadatacenter.org/template-fields/7ee0c76f-fe4d-43dc-a45f-1b84ae844698",
      "$schema": "http://json-schema.org/draft-04/schema#"
    }

Here we have a field type of attribute-value and a property specification for the value requiring a field called cedar:attributeFieldName.

Multi-instance will work out-of the box in templates.

Attribute-value field values in template instances can use this field to point to the attribute-value field in the template that specified them (that is, the schema:name field in the field specification).

For example if a Metadata Editor user creates an attribute-value field using the "My Attribute/Value" field with the name "Attribute 1" and a value of "Fred" the instance could look as follows:

"Attribute 1": 
{
  "@value": "Fred",
  "cedar:attributeFieldName": "My Attribute/Value"
}

This approach means that attribute-value fields specified by users in the Metadata Editor become first class fields in the instance and can be mapped directly to RDF triples. It will also require a context entry for the field. When the name is changed in the Metadata Editor the context must be updated.

Will need to discuss with @willrett and @marcosmro. This approach will not be super easy for the Metadata Editor to manage.

Some additional points:

. Model work required to support this. Since we are effectively adding new fields to instances that are not pre-named in the template specification we will need to allow additional properties at the JSON Schema level and require that the only new fields allowed are attribute-value fields.

[martinjoconnor]

Marcos suggested using the schema:isBasedOn field instead of a custom field. It is similar in operation to the use of this field in template instances. It will contain the ID of the field specification.

  "My Attribute/Value": {
      "@type": "https://schema.metadatacenter.org/core/TemplateField",
      "@context": { ... },
      "type": "object",
      "title": "F1 field schema",
      "description": "F1 field schema generated by the CEDAR Template Editor 1.5.0",
      "_ui": { "inputType": "attribute-value" },
      "_valueConstraints": { "requiredValue": false },
      "properties": {
        "@type": { ... },
        "@value": { "type": [ "string", "null" ] },
        "rdfs:label": { "type": [ "string", "null" ],
        "schema:isBasedOn": { "@type": "@id" }
        }
      },
      "required": [ "@value" ],
      "schema:name": "My Attribute/Value",
      "schema:description": "",
      "pav:createdOn": "2017-11-07T14:03:32-0800",
      "pav:createdBy": "https://metadatacenter.org/users/6e574d2d-8b29-48b2-b9f3-6ea463786c67",
      "pav:lastUpdatedOn": "2017-11-07T14:03:32-0800",
      "oslc:modifiedBy": "https://metadatacenter.org/users/6e574d2d-8b29-48b2-b9f3-6ea463786c67",
      "schema:schemaVersion": "1.3.0",
      "additionalProperties": false,
      "@id": "https://repo.staging.metadatacenter.org/template-fields/7ee0c76f-fe4d-43dc-a45f-1b84ae844698",
      "$schema": "http://json-schema.org/draft-04/schema#"
    }

We do NOT add the above field name ("My Attribute/Value") to the template's required field because a field of this name will not actually appear in the instances - the user will be specifying the names of attribute-value fields in the Metadata Editor.

A field value with a user-selected name of "Attribute 1" could then look as follows:

"Attribute 1": 
{
  "@value": "Fred",
  "schema:isBasedOn": "https://repo.staging.metadatacenter.org/template-fields/7ee0c76f-fe4d-43dc-a45f-1b84ae844698"
}

We can use an additionalProperties specification as follows to allow new attribute-value fields to appear in the instances:

"additionalProperties": {
      "type": "object",
      "title": "Attribute-value field schema",
      "description": "Attribute-value field schema generated by the CEDAR Template Editor 1.5.0",
      "properties": {
        "rdfs:label": { "type": [ "string", "null" ] },
        "@value": { "type": [ "string", "null" ] },
        "@type": { "@type": "@id" }
        "schema:isBasedOn": { "@type": "@id" }
      },
      "required": [ "schema:isBasedOn" ],
      "additionalProperties": false
  }

Any additional attribute fields in an instance must follow this specification and must have a schema:isBasedOn field pointing to the field specification in the template. The slightly funky thing in this approach is that the source field specification in the schema is not actually used to specify the format of the field instance - instead, the additionalProperties is. The source field specification is however used for value constraints etc.

[martinjoconnor]

Validation, patching, and documentation tasks: #58, #59, #60

[martinjoconnor]

Note that when a user adds a new attribute/value field in the Metadata Editor an @context entry must be made in the instance for that field (and removed when an attribute/value field is removed). (Entries for existing fields are added to the @context field for an instance by the Metadata Editor when the instance is first created.)

[martinjoconnor]

Some model-level implementing tasks:

#69
#70

[martinjoconnor]

Final representation is option #3 here:

https://docs.google.com/document/d/1eMXLOan1E9YVeByrReHO2T6hfrWsR-6Jr525TpkGkNY/edit

[martinjoconnor]

See metadatacenter-attic/cedar-docs#8 for field representation.