@[toc](Table of Contents) # Beta SHARE Metadata Schema The beta SHARE metadata schema is based on a [json-schema](http://json-schema.org/). Details, code generating schemas, examples and more information available on the [SHARE Schema repo on github](https://github.com/JeffSpies/SHARE-Schema). Many of the fields in this schema are not required. The only required fields include: - title - contributors - uris - providerUpdatedDateTime See the schema below for details on each of the fields. ## Current Schema Here is the current schema: ``` --- definitions: otherProperties: type: "object" properties: name: description: A name that describes this collection of properties. type: "string" description: description: A description of this collection of properties. type: "string" properties: description: The collection of key/value pair properties. type: "object" uri: description: A URI that points to the definition, schema, and/or vocabulary of this entry. type: "string" format: "uri" required: - name - properties license: type: "object" properties: uri: description: The HTTP URI of the license of the object or--if startDate and endDate are included--in effect during the period listed. type: string format: uri description: description: Text describing to what aspect of the object the license is applied. type: string startDate: description: The date and time at which the license will apply to this object. If the resource was always licensed this way, then this date can be omitted. type: string format: date-time endDate: description: The date and time at which this resource will no longer be licensed in this way. type: string format: date-time required: - "uri" person: description: A person that is a contributor to the research object. type: "object" properties: name: description: The name of the person if familyName, givenName, and/or additionalName. type: "string" sameAs: description: An array of identifiers expressed as HTTP URIs that describe the person. For example, an ORCID, ResearcherID, arXiv author ID, ScopusID, ISNI, or other unique identifier expressed as an HTTP URI. type: "array" items: description: An HTTP URI that describes the person. type: "string" format: "uri" familyName: description: Also called the "last name", this element is preferred over using the combined "name" field. type: "string" givenName: description: Also called the "first name", this element is preferred over using the combined "name" field. type: "string" additionalName: description: Also called the "middle name", this element will be derived from the creator.name by SHARE if not supplied by the source. type: "string" email: description: The email address for this person. type: "string" format: "email" affiliation: description: The organization(s) that this person is affiliated with. For example, a school/university. type: "array" items: $ref: "#/definitions/organization" required: - "name" organization: type: "object" description: An organization or institution. properties: name: description: The name of the organization. type: "string" sameAs: type: "array" description: "Identifiers that describe this organization" items: type: "string" format: "uri" description: "A single HTTP URI that describes this organization" email: type: "string" format: "uri" description: "An email address for this organization" required: - "name" award: description: The award made in support of the object. type: object properties: awardName: description: The textual representation of the award identifier as issued by the sponsor. type: "string" awardIdentifier: type: "string" format: "uri" description: An HTTP URI for the award. required: - awardName sponsor: description: "This describes the sponsor of the resource." type: object properties: sponsorName: description: "The name of the entity responsible for sponsoring the resource, recorded here as text." type: "string" sponsorIdentifier: type: "string" format: "uri" description: "A globally unique identifier for the sponsor of the resource should be recorded here." required: - "sponsorName" sponsorship: type: "object" description: "A sponsorship associated with the resource." properties: award: $ref: "#/definitions/award" sponsor: $ref: "#/definitions/sponsor" required: - "sponsor" $schema: "http://json-schema.org/draft-04/schema#" type: "object" properties: title: description: The title and any sub-titles of the resource. type: "string" contributors: description: The people or organizations responsible for making contributions to an object. type: array items: anyOf: - $ref: "#/definitions/person" - $ref: "#/definitions/organization" description: description: A textual description of the resource. type: "string" uris: type: object required: - canonicalUri properties: canonicalUri: description: The preferred persistent HTTP URI that represents the research object. This should be repeated in exactly one other field in the uris object. type: string format: uri anyOf: objectUris: description: A persistent HTTP URI that points directly to the research object. type: array items: type: string format: uri descriptorUris: description: A persistent HTTP URI that points to a description of the research object. type: array items: type: string format: uri providerUris: description: "The persistent HTTP URI that points to the object's record at the SHARE provider regardless of format." type: array items: type: string format: uri providerUpdatedDateTime: description: The date and time the provider describing the object has been updated about either the creation or update of an object by its contributors. E.g., this may be the date a manuscript is published, but not necessarily the date the manuscript was written. type: string format: date-time freeToRead: type: "object" description: A date range specifying when this research object will be accessible, without restrictsions such as fee or registration). If the object is free to read, then only the startDate is required. properties: startDate: description: The date and time at which the object will be accessible. If the resource was always free to read, then the date the object was created should be used. type: "string" format: date endDate: description: The date and time at which restrictions such as fees or registrations will be in place limiting accessibility. type: "string" format: date required: - startDate languages: description: The primary languages in which the content of the resource is presented. Values used for this element MUST conform to ISO 639–3. This offers three letter tags e.g. "eng" for English. type: array items: type: string pattern: "[a-z][a-z][a-z]" licenses: description: The licenses under which the object has been released. type: "array" items: $ref: "#/definitions/license" publisher: description: "This element contains the name of the entity, typically a 'publisher', responsible for making the version of record of the resource available. This could be a person, organisation or service" type: "object" anyOf: - $ref: "#/definitions/person" - $ref: "#/definitions/organization" sponsorships: description: "Sponsorships associated with the object" type: "array" items: $ref: "#/definitions/sponsorship" subjects: description: "The topic or domain of the object. Follows recommendations of http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=elements#terms-subject" type: "array" items: type: string tags: description: Non-hierarchical terms or keywords assigned to an object to aid browsing or searching. type: array items: type: string version: description: Infomation about this version of the object. type: object properties: versionId: description: The name or number representing this version of the object. versionDateTime: description: The date and time the object was created or updated by its contributors. If the data for the object describes the first version of that object, it will be the date and time of object creation, otherwise it will be considered the date and time the object was updated. type: string format: date-time versionOf: description: If the object is an update, the HTTP URI of the object the content is updating. Depending upon what the upate is relative to, that could be the object at creation or a previous version. type: string format: uri otherProperties: description: Any structured or unstructured properties (properties that do or do not include URIs to definitions) that do not fall into the schema provided. type: "array" items: $ref: "#/definitions/otherProperties" shareProperties: description: Properties that are generated and/or organized by the SHARE system (e.g., timestamps of when SHARE processes data). These properities are used internally and are not guaranteed to remain consistent. type: object required: - title - contributors - uris - providerUpdatedDateTime ``` Here is the current schema in json form: ``` { "definitions": { "person": { "required": [ "name" ], "type": "object", "description": "A person that is a contributor to the research object.", "properties": { "affiliation": { "items": { "$ref": "#/definitions/organization" }, "type": "array", "description": "The organization(s) that this person is affiliated with. For example, a school/university." }, "givenName": { "type": "string", "description": "Also called the \"first name\", this element is preferred over using the combined \"name\" field." }, "additionalName": { "type": "string", "description": "Also called the \"middle name\", this element will be derived from the creator.name by SHARE if not supplied by the source." }, "name": { "type": "string", "description": "The name of the person if familyName, givenName, and/or additionalName." }, "sameAs": { "items": { "type": "string", "description": "An HTTP URI that describes the person.", "format": "uri" }, "type": "array", "description": "An array of identifiers expressed as HTTP URIs that describe the person. For example, an ORCID, ResearcherID, arXiv author ID, ScopusID, ISNI, or other unique identifier expressed as an HTTP URI." }, "familyName": { "type": "string", "description": "Also called the \"last name\", this element is preferred over using the combined \"name\" field." }, "email": { "type": "string", "description": "The email address for this person.", "format": "email" } } }, "sponsor": { "required": [ "sponsorName" ], "type": "object", "description": "This describes the sponsor of the resource.", "properties": { "sponsorName": { "type": "string", "description": "The name of the entity responsible for sponsoring the resource, recorded here as text." }, "sponsorIdentifier": { "type": "string", "description": "A globally unique identifier for the sponsor of the resource should be recorded here.", "format": "uri" } } }, "license": { "required": [ "uri" ], "type": "object", "properties": { "startDate": { "type": "string", "description": "The date and time at which the license will apply to this object. If the resource was always licensed this way, then this date can be omitted.", "format": "date-time" }, "endDate": { "type": "string", "description": "The date and time at which this resource will no longer be licensed in this way.", "format": "date-time" }, "uri": { "type": "string", "description": "The HTTP URI of the license of the object or--if startDate and endDate are included--in effect during the period listed.", "format": "uri" }, "description": { "type": "string", "description": "Text describing to what aspect of the object the license is applied." } } }, "organization": { "required": [ "name" ], "type": "object", "description": "An organization or institution.", "properties": { "sameAs": { "items": { "type": "string", "description": "A single HTTP URI that describes this organization", "format": "uri" }, "type": "array", "description": "Identifiers that describe this organization" }, "name": { "type": "string", "description": "The name of the organization." }, "email": { "type": "string", "description": "An email address for this organization", "format": "uri" } } }, "otherProperties": { "required": [ "name", "properties" ], "type": "object", "properties": { "description": { "type": "string", "description": "A description of this collection of properties." }, "properties": { "type": "object", "description": "The collection of key/value pair properties." }, "name": { "type": "string", "description": "A name that describes this collection of properties." }, "uri": { "type": "string", "description": "A URI that points to the definition, schema, and/or vocabulary of this entry.", "format": "uri" } } }, "award": { "required": [ "awardName" ], "type": "object", "description": "The award made in support of the object.", "properties": { "awardIdentifier": { "type": "string", "description": "An HTTP URI for the award.", "format": "uri" }, "awardName": { "type": "string", "description": "The textual representation of the award identifier as issued by the sponsor." } } }, "sponsorship": { "required": [ "sponsor" ], "type": "object", "description": "A sponsorship associated with the resource.", "properties": { "sponsor": { "$ref": "#/definitions/sponsor" }, "award": { "$ref": "#/definitions/award" } } } }, "$schema": "http://json-schema.org/draft-04/schema#", "required": [ "title", "contributors", "uris", "providerUpdatedDateTime" ], "type": "object", "properties": { "publisher": { "type": "object", "anyOf": [ { "$ref": "#/definitions/person" }, { "$ref": "#/definitions/organization" } ], "description": "This element contains the name of the entity, typically a 'publisher', responsible for making the version of record of the resource available. This could be a person, organisation or service" }, "description": { "type": "string", "description": "A textual description of the resource." }, "contributors": { "items": { "anyOf": [ { "$ref": "#/definitions/person" }, { "$ref": "#/definitions/organization" } ] }, "type": "array", "description": "The people or organizations responsible for making contributions to an object." }, "title": { "type": "string", "description": "The title and any sub-titles of the resource." }, "shareProperties": { "type": "object", "description": "Properties that are generated and/or organized by the SHARE system (e.g., timestamps of when SHARE processes data). These properities are used internally and are not guaranteed to remain consistent." }, "otherProperties": { "items": { "$ref": "#/definitions/otherProperties" }, "type": "array", "description": "Any structured or unstructured properties (properties that do or do not include URIs to definitions) that do not fall into the schema provided." }, "tags": { "items": { "type": "string" }, "type": "array", "description": "Non-hierarchical terms or keywords assigned to an object to aid browsing or searching." }, "uris": { "type": "object", "properties": { "anyOf": { "canonicalUri": { "type": "string", "description": "The preferred persistent HTTP URI that represents the research object. This should be repeated in exactly one other field in the uris object.", "format": "uri" }, "providerUris": { "items": { "type": "string", "format": "uri" }, "type": "array", "description": "The persistent HTTP URI that points to the object's record at the SHARE provider regardless of format." }, "descriptorUris": { "items": { "type": "string", "format": "uri" }, "type": "array", "description": "A persistent HTTP URI that points to a description of the research object." }, "objectUris": { "items": { "type": "string", "format": "uri" }, "type": "array", "description": "A persistent HTTP URI that points directly to the research object." } } } }, "languages": { "items": { "pattern": "[a-z][a-z][a-z]", "type": "string" }, "type": "array", "description": "The primary languages in which the content of the resource is presented. Values used for this element MUST conform to ISO 639\u20133. This offers two and three letter tags e.g. \"en\" or \"eng\" for English and \"en-GB\" for English used in the UK." }, "providerUpdatedDateTime": { "type": "string", "description": "The date and time the provider describing the object has been updated about either the creation or update of an object by its contributors. E.g., this may be the date a manuscript is published, but not necessarily the date the manuscript was written.", "format": "date-time" }, "sponsorships": { "items": { "$ref": "#/definitions/sponsorship" }, "type": "array", "description": "Sponsorships associated with the object" }, "version": { "type": "object", "description": "Infomation about this version of the object.", "properties": { "versionId": { "description": "The name or number representing this version of the object." }, "versionDateTime": { "type": "string", "description": "The date and time the object was created or updated by its contributors. If the data for the object describes the first version of that object, it will be the date and time of object creation, otherwise it will be considered the date and time the object was updated.", "format": "date-time" }, "versionOf": { "type": "string", "description": "If the object is an update, the HTTP URI of the object the content is updating. Depending upon what the upate is relative to, that could be the object at creation or a previous version.", "format": "uri" } } }, "freeToRead": { "required": [ "startDate" ], "type": "object", "description": "A date range specifying when this research object will be accessible, without restrictsions such as fee or registration). If the object is free to read, then only the startDate is required.", "properties": { "startDate": { "type": "string", "description": "The date and time at which the object will be accessible. If the resource was always free to read, then the date the object was created should be used.", "format": "date" }, "endDate": { "type": "string", "description": "The date and time at which restrictions such as fees or registrations will be in place limiting accessibility.", "format": "date" } } }, "licenses": { "items": { "$ref": "#/definitions/license" }, "type": "array", "description": "The licenses under which the object has been released." }, "subjects": { "items": { "type": "string" }, "type": "array", "description": "The topic or domain of the object. Follows recommendations of http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=elements#terms-subject" } } } ``` ## Example Here is an example of a valid document that will validate against this schema. ```json { "contributors": [ { "name": "Dustin Runnels", "sameAs": [ "https://osf.io/thing" ], "familyName": "Runnels", "givenName": "Dustin", "additionalName": "Golddust", "email": "golddust@example.com" }, { "name": "Cody Madness Runnels", "affiliation": [ { 'name': 'Institution of Hard Knocks" } ] } ], "languages": [ "eng" ], "description": "Some important research about gold isotopes.", "providerUpdatedDateTime": "2014-12-12T00:00:00Z", "freeToRead": { "startDate": "2014-09-12", "endDate": "2014-10-12" }, "licenses": [ { "uri": "http://www.mitlicense.com", "startDate": "2014-10-12", "endDate": "2014-11-12" } ], "publisher": { "name": "Roger Ebert Inc", "email": "roger@example.com" }, "sponsorships": [ { "award": { "awardName": "Participation", "awardIdentifier": "http://example.com" }, "sponsor": { "sponsorName": "Orange", "sponsorIdentifier": "http://example.com/orange" } } ], "title": "Interesting research", "version": { "versionId": "someID" }, "uris": { "canonicalUri": "http://example.com", "providerUris": [ 'http://provideruri1.source.com/doc1', 'http://provideruri2.source.com' ] } } ```