Awesome

<a id="top"></a>

Table of Contents

• Updates

• About

• Goals

• Approach

• Vocabulary Prefixes

• schema.org Extensions

• Graphical Notation

• Publishing schema.org JSON-LD

  • Describing a Repository
    • Repository - Fields
    • Repository - Funding Source
    • Repository - Types of Resources
    • Repository - Outreach Activities
    • Repository - Identifier
    • Repository - Policies
    • Repository - Services
    • Repository - Data Collections
  • Describing a Dataset
    • Dataset - Identifier
    • Dataset - Variables
    • Dataset - DataCatalog
    • Dataset - Distributions
      • Accessing Data through a Service Endpoint
    • Dataset - Temporal
    • Dataset - Spatial
      • GeoCoordinates
      • GeoShape
    • Dataset - Creators/Contributors
    • Dataset - Publisher/Provider
    • Dataset - Protocols
    • Dataset - Funding

• Examples

• Issues

• Advanced Publishing Techniques

  • How to use external vocabularies
  • Publishing more detail for categories/disciplines for a repository
  • Attaching Physical Samples to a Dataset

<a id="updates"></a>

UPDATES

Mar 21 2018 Adding an example of how to attach physical samples, and their IGSN identifiers, to a Dataset. See: Attaching Physical Samples to a Dataset

Mar 15 2018

Adding the schema:identifier field can be done in three ways - a text description, a URL, or by using the schema:PropertyValue type to describe the identifier in more detail. We highly recommend using the schema:PropertyValue as the use of text or url does not get indexed properly by Google and other JSON-LD testing tools due to an issue with the properties definition.

Mar 1 2018

We've updated our documentation for fixing our use of schema:additionalType and schema:propertyID to use fully-qualified URLs. This corrects the mistake of using a vocabulary prefix such as gdx: to make reference to a vocabulary class. An example of this fix for schema:additionalType:

OLD

NEW

This pattern is also applied to the schema:propertyID in this way:

OLD

NEW

<a id="about"></a>

About

Serves the vocabulary in JSON-LD at https://geodex.org/voc/.

<a id="goals"></a>

Goals

1. To produce quality schema.org markup with additional extensions to schema.org classes to help improve harvesting technologies.

2. Produced markup will pass the Google Structured Data Testing Tool with 0 errors.

Approach

The preferred format for schema.org markup by its harvesters is JSON-LD. For a primer on JSON-LD, see https://json-ld.org/

To produce quality schema.org, all extensions to schema.org classes will be made through the use of the recommended property schema:additionalType.

The gdx: vocabulary will extend schema.org using rdfs:subClassOf in it's formal ontology, but in schema.org this doesn't translate into the use of JSON-LD's @type as traditional RDF publishing would encourage.

<a id="prefixes"></a>

Vocabulary Prefixes

schema: the defacto vocabulary for publishing structured data in web pages for search engine harvesting

gdx: the P418 project's vocabulary

geolink: an EarthCube Building Block focusing on describing discovery-level metadata for datasets

earthcollab: an EarthCube Building Block focusing on extensions to the ViVO ontology

vivo: the ViVO ontology

geo-upper: a segment of the Geoscience Standard Names Ontology, an EarthCube product. This ontology could be used when describing dataset variables.

datacite: describes persistent identifier schemes like DOI, ARK, URI for helping to represent PIDs.

<a id="extensions"></a>

Schema.org Extensions

From P418, the vocabulary we built specifically for addressing gaps in schema.org and other EarthCube and community ontologies, we have:

P418: http://geodex.org/voc/

• Classes: http://geodex.org/voc/?show=classes
  • gdx:ResearchRepositoryService
• Properties: http://geodex.org/voc/?show=properties
  • gdx:fundedBy
• NamedIndividuals (these are classes but tightly coupled to existing schema.org classes): http://geodex.org/voc/?show=namedindividuals
  • gdx:OutreachActivities
  • gdx:OutreachActivity-Training
  • gdx:OutreachActivity-UserSupport
  • gdx:OutreachActivity-UserWorkshop
  • gdx:Protocol-Access
  • gdx:Protocol-License
  • gdx:Protocol-PreservationPolicy
  • gdx:Protocol-ResourceSubmissionPolicy
  • gdx:Protocol-TermsOfUse
  • gdx:ResearchResourceTypes
  • gdx:SearchService
  • gdx:SitemapXML
  • gdx:SubmissionService
  • gdx:SyndicationService

We also use terms from other vocabularies:

GeoLink

• Classes: Dataset, PhysicalSample, Identifier, MeasurementType, Person, Organization, Award

EarthCollab

• Classes: Parameter

ViVO (part of EarthCollab)

• Classes: Dataset

GeoStandardNames

• Classes: we give an example of how to use one of his terms (http://www.geoscienceontology.org/geo-lower/quantity#longitude)

DataCite

• Classes: Identifier
• NamedIndividual: DOI, ORCID

<a id="graphical-notation"></a>

Graphical Notation

The graphs display the classes, properties and literals for producing valid schema.org markup.

Back to top

<a id="schemaorg-jsonld"></a>

Schema.org JSON-LD

Schema.org's preferred format for markup is JSON-LD. THere are a number of tools that will help build valid schema.org JSON-LD.

• Web UI for constructing schema.org: https://schema.pythonanywhere.com/

  • Jumpstart into specific Types:
    • Service
    • Organization
      • ContactPoint
      • PropertyValue aka Identifier
    • DigitalDocument
    • OfferCatalog
    • ServiceChannel
      • Service
    • Dataset
      • DataDownload
      • DataCatalog
      • Person aka Author/Contributor
      • Organization aka Publisher, Provider, Funder
      • Place
        • GeoShape
        • GeoCoordinates
      • PropertyValue aka Variable, Identifier
      • Event
        • CreativeWork
          • Vehicle

• Google Testing Tool for schema.org: https://search.google.com/structured-data/testing-tool/u/0/

  • Error Guide: https://www.schemaapp.com/tips/structured-data-testing-tool-error-guide/

Back to top

<a id="repository"></a>

Describing a Repository

In schema.org, we model a repository as both an schema:Organization and a schema:Service. This double-typing gives us the most flexibility in describing the characteristics of the organization providing the service and the services offered by the organization. Becuase the Service class in schema.org is very broad, to uniquely identify repositories curating research products, this vocabulary defines an extension to schema:Service as gdx:ResearchRepositoryService.

The other fields you can use to describe the Organziation and the Service are:

<a id="repository-fields"></a>

• schema:legalName should be the official name of the repository,
• schema:name can be an acronym or the name typcially used for the repository,
• schema:url should be the url of your repository's homepage,
• schema:description should be text describing your repository,
• schema:sameAs can be used to link the repository to other URLs such as Re3Data, Twitter, LinkedIn, etc.,
• schema:category can be used to describe the discipline, domain, area of study that encompasses the repository's holdings.

(See advanced publishing techniques for how to describe categories/disciplines in more detail than just simple text.)

If you are using the "@id" attribute for your Repository, you can specify the schema:provider of the schema:Service in this way:

However, if your repository has a situation where multiple organizations act as the provider or you want to recognize a different organization as the provider of the repository's service, schema:provider can be used in this way:

Adding additional fields of schema:Organization:

If this Organization has a parent entity such as a college, university or research center, that information can be provided using the schema:parentOrganization property:

Back to top

<a id="repository-funding-source"></a>

Describing a Repository's Funding Source

To describe the funding source of a repository, you use the schema:funder property of schema:Organization:

<a id="repository-identifier"></a>

Describing a Repository's Identifier

Some organizations may have a persistent identifier (DOI) assigned to their organization from authorities like the Registry of Research Data Repositories (re3data.org). The way to describe these organizational identifiers is to use the schema:identifier property in this way:

We add the datacite vocabulary to the @context because the Datacite Ontology available at http://purl.org/spar/datacite/ has URIs to describe a DOI, ORCiD, ARK, URI, URN - all identifier scheme that help for disamiguating identifiers. To properly disambiguate a globally unique identifier, 2 pieces of information are needed - 1) the identifier value and 2) the scheme that on which that identifier exists. Some examples of this concept for common identifiers are:

When describing PIDs, it's important to include both of these pieces for downstream activities like searching and linking resources. FOor example, a user may want to query for all repositories with a DOI identifier or all Datasets authored by a researcher with an ORCiD. These types of filters become more difficult when only the URL to these identifiers are provided. The reason here is that there are multiple URLs for an persistent identifier. On example is the DOI:

• http://doi.org/10.17616/R37P4C
• https://doi.org/10.17616/R37P4C
• http://dx.doi.org/10.17616/R37P4C
• https://dx.doi.org/10.17616/R37P4C

So, the best practice is to provide the scheme and value for an identifier, but you can also provide a URL representation using the schema:url property.

Back to top

<a id="repository-resource-types"></a>

Describing a Repository's Types of Resources

To describe the types of research resources a repository curates, we use the schema:OfferCatalog. With an extension of gdx:ResearchResourceTypes, we define that the OfferCatalog will be a list of types that are dervied from schema:CreativeWork.

Notice, that we use @id to describe the type of resource. To reference schema.org classes using @id properly, we must add schema.org to the @context with a prefix name. Here, we chose schema: in the @context, thus we use schema:Dataset to say that our repository curates resource types of schema.org/Dataset.

Because schema.org does not have a class for a Physical Sample yet, we use teh calss definition from the EarthCube GeoLink vocabulary to specify that this repository curates physical samples. We add geolink: to the @context section, and then specify geolink:PhysicalSample as another @id offered by this repository.

<a id="repository-outreach-activities"></a>

Describing a Repository's Outreach Activities

To describe the outreach activities of a repository, we again use the schema:OfferCatalog but specify it's schema:additionalType to be gdx:OutreachActivities:

These Action items above are not instances of actual events, but specify the type of potential events a repository may hold. To describe a specific schema:Event related to one of these activities, you could publish on a different web page in this way:

<a id="repository-policies"></a>

Describing a Repository's Policies

If your repository has policy documents about access control, terms of use, etc. You can provide those using the schema:publishingPrinciples field. Becuase schema.org does not make a distiction for the types of these documents, P418 has created some class names for some common policy document types. These will help make it clear to users what types of policies you have. If you would like us to add more, please let us know by creating an Issue.

Back to top

<a id="repository-services"></a>

Describing a Repository's Services

For repositories might offer services for accessing data as opposed to directly accessing data files. The schema:Service allows us to describe these services as well as repository searches, data submission services, and syndication services. In this first example, we describe a search service at the repository using schema:ServiceChannel.

By specifying the [schema:potentialAction(https://schema.org/potentialAction), we create a machine-actionable way to execute searches. This means that an EarthCube Registry could take a user submitted query, and pass it along to the repository for the EarthCube Registry user.

If your repository does have datasets or other resources with schema.org JSON-LD markup on their landing pages, Google recommends that all URLs be put inside a sitemap.xml file. To create a sitemap.xml, go here. To describe your sitemap.xml, add a schema:ServiceChannel similar to the following markup:

Back to top

<a id="repository-data-collections"></a>

Describing a Repository's Data Collections

If your repository has a concept of a data collection, some grouping of a number of datasets, we can use the schema:DataCatalog to describe these collections using the schema:OfferCatalog. One exampel of a DataCatalog might be to group datasets by a categorization such as 'biological data' or 'chemical data'. Or a catalog could be grouped by instrument, parameter or whatever logical grouping a repository may have.

Back to top

<a id="dataset-diagram"></a>

Describing a Dataset

The schema:Dataset is a very expressive type within schema.org.

However, Google has drafted a guide to help publishers. THe guide describes the only required fields as - name and description.

• name - A descriptive name of a dataset (e.g., “Snow depth in Northern Hemisphere”)
• description - A short summary describing a dataset.

The guide suggests the following recommended fields:

• url - Location of a page describing the dataset.
• sameAs - Other URLs that can be used to access the dataset page. A link to a page that provides more information about the same dataset, usually in a different repository.
• version - The version number or identifier for this dataset (text or numeric).
• isAccessibleForFree - Boolean (true|false) speficying if the dataset is accessible for free.
• keywords - Keywords summarizing the dataset.
• license - A license under which the dataset is distributed (text or URL).
• identifier - An identifier for the dataset, such as a DOI. (text,URL, or PropertyValue).
• variableMeasured - What does the dataset measure? (e.g., temperature, pressure)

Back to top

<a id="dataset-identifiers"></a> Adding the schema:identifier field can be done in three ways - a text description, a URL, or by using the schema:PropertyValue type to describe the identifier in more detail. We highly recommend using the schema:PropertyValue as the use of text or url does not get indexed properly by Google and other JSON-LD testing tools due to an issue with the properties definition.

Describing a Dataset Identifier

In it's most basic form, the identifier as a schema:PropertyValue can be published as:

The Persistent Identifier, such as a DOI, ARK, URL, etc as a schema:PropertyValue can be published using the DataCite Ontology Resource Identifier Scheme to define the identifier as:

schema:Dataset also defines a field for the schema:citation as either text or a schema:CreativeWork. To provide citation text:

NOTE: If you have a DOI, the citation text can be automatically generated for you by querying a DOI URL with the Accept Header of 'text/x-bibliography'.

Back to top

<a id="dataset-variables"></a> Adding the schema:variableMeasured field can be done in two ways - a text description of each variable or by using the schema:PropertyValue type to describe the variable in more detail. We highly recommend using the schema:PropertyValue.

Describing a Dataset's Variables

In it's most basic form, the variable as a schema:PropertyValue can be published as:

<a id="gsn-example"></a> A fully-fleshed out example that uses a vocabulary to describe the variable can be published as:

Back to top

<a id="dataset-catalog"></a>

Describing a Dataset's Catalog

For some repositories, defining a one or many data collections helps contextualize the datasets. In schema.org, you define these collections using schema:DataCatalog.

The most optimal way to use these DataCatalogs for a repository is to define these catalogs as an "offering" of your repository and including the @id property to be reused in the dataset JSON-LD. For example, the repository JSON-LD defines a schema:DataCatalog with the

"@id": "https://www.sample-data-repository.org/collection/biological-data".

In the dataset JSON-LD, we reuse that @id to say a dataset belongs in that catalog:

Back to top

<a id="dataset-distros"></a>

Describing a Dataset's Distributions

Where the schema:url property of the Dataset should point to a landing page, the way to describe how to download the data in a specific format is through the schema:distribution property. The "distribution" property describes where to get the data and in what format by using the schema:DataDownload type. If your dataset is not accessible through a direct download URL, but rather through a service URL that may need input parameters jump to the next section Accessing Data through a Service Endpoint.

For data available in multipe formats, there will be multiple values of the schema:DataDownload:

<a id="dataset-service-endpoint"></a>

Accessing Data through a Service Endpoint

If access to the data requires some input parameters before a download can occur, we can use the schema:potentialAction in this way:

Here, we use the schema:SearchAction type becuase it lets you define the query parameters and HTTP methods so that machines can build user interfaces to collect those query parmaeters and actuate a request to provide the user what they are looking for.

Back to top

<a id="dataset-temporal"></a>

Describing a Dataset's Temporal Coverage

Temporal coverage is a difficult concept to cover across all the possible scenarios. Schema.org uses ISO 8601 standard to describe time intervals and time points, but doesn't provide capabilities for geologic time scales or dynamically generated data up to present time. We ask for your feedback on any temporal coverages you may have that don't currently fit into schema.org. You can follow [similar issues at the schema.org Github issue] queue(https://github.com/schemaorg/schemaorg/issues/242)

To represent a single date and time:

Or a single date:

Or a date range:

Schema.org also lets you provide date ranges and other temporal coverages through the DateTime data type. For more granular temporal coverages go here: http://schema.org/DateTime.

Back to top

<a id="dataset-spatial"></a>

Describing a Dataset's Spatial Coverage

The types of spatial coverages in schema.org are

• point - specify the schema:latitude and schema:longitude properties of the schema:GeoCoordinates]() type.

The following shapes use the schema:GeoShape type where a 'point' is defined as a latitude/longitude pair separated by a comma.

• line - a series of two or more point objects separated by space.
• polygon - a series of four or more space delimited points where the first and final points are identical.
• box - two points separated by a space character where the first point is the lower corner and the second point is the upper corner.

These spatial definitiosn were added to schema.org very early on in its development where they decided to follow the GeoRSS specification. While this is not ideal, there are ongoing conversations about improving this in schema.org.

<a id="dataset-spatial-point"></a> A point, or coordinate, would defined in this way:

<a id="dataset-spatial-shape"></a> All other shapes, are defined using the schema:GeoShape:

A polygon

A box where 'lower-left' corner is 39.3280/120.1633 and 'upper-right' corner is 40.445/123.7878

For Project418, we feel the defined spatial coverages are inadequate for the needs of our community, but we also recognize that schema.org continues to hear the needs of its schema.org publishers on these issues.

To alleviate some of the pain of converting spatial information into these defined shapes, Project418 offers support for GeoJSON by using the schema:subjectOf property of the schema:Place type. The schema:fileFormat property should have the value of the GeoJSON mime type application\/vnd.geo+json and the schema:text property should be the encoded value of the GeoJSON itself:

We also recognize that there is no defined property for specifying a Coordinate Reference System, but we see from the schema.org issue queue that this has been mentioned.

<a id="dataset-multiple-geometries"></a> If you have multiple geometries, you can publish those by making the schema:geo field an array of GeoShape or GeoCoordinates like so:

Back to top

<a id="dataset-creator_contributor"></a>

Describing a Dataset's Creators/Contributors

People can be linked to datasets iusing three fields: author, creator, and contributor. Since schema:contributor is defined as a secondary author, and schema:Creator is defined as being synonymous with the schema:author field, we recommend using the more expressive fields of creator and contribulds of creator and contributor. But using any of these fields are okay. Becuase there are more things that can be said about how and when a person contributed to a Dataset, we use the schema:Role. You'll notice that the schema.org documentation does not state that the Role type is an expected data type of author, creator and contributor, but that is addressed in this blog post introducing Role into schema.org. Thanks to Stephen Richard for this contribution

NOTE that the Role inherits the property creator and contributor from the Dataset when pointing to the schema:Person.

If a single Person plays multiple roles on a Dataset, each role should be explicitly defined in this way:

Notice that since Uta Passow has already been defined in the document with "@id": "https://www.bco-dmo.org/person/51317" for her role as Principal Investigator, the @id can be used for her role as Contact by defining the Role's creator as "creator": { "@id": "https://www.bco-dmo.org/person/51317" }.

Back to top

<a id="dataset-publisher_provider"></a>

Describing a Dataset's Publisher/Provider

If your repository is the publisher and/or provider of the dataset then you don't have to describe your repository as a schema:Organziation if your repository markup includes the @id. For example, if you published repository markup such as:

then you can reuse that @id here. Harvesters such as Google and Project418 will make the appropriate linkages and your dataset publisher/provider can be published in this way:

Otherwise, you can define the organization inline in this way:

Back to top

<a id="dataset-protocols"></a>

Describing a Dataset's Protocols

Datasets can have a number of policies and protocols attached to them - Terms of Use, access restrictions, certain licenses, etc. If you want to represent one or more of these protocols and there is a URL at which a user can read that protocol, we can use the schema:DigitalDocument to describe the protocol using the schema:publishingPrinciples field.

P418 has created some class names for some common protocol document types. These will help make it clear to users what types of policies you have. If you would like us to add more, please let us know by creating an Issue.

Back to top

<a id="dataset-funding"></a>

Trying to describe a Dataset's funding award is one area of schema.org that doesn't fit all that well. There is a lot of discussion on this topic already happening with schema.org governance. Schema.org's most recent communication with P418 recommended that the award be something generated from the schema:funder. We feel the best class to classify as an Award until this is addressed by schema.org is the schema:Offer. If you specify an Award, you should also use the gdx:fundedBy property to directly link the Dataset to the Award in this way.

Describing a Dataset's Funding

• schema:name - The award title
• schema:description - The award description/abstract
• schema:identifier - The award identifier,number,etc.
• schema:validFrom - The award start date
• schema:validThrough - The award end date

Back to top

<a id="examples"></a>

Examples

All examples can be found at: https://github.com/earthcubearchitecture-project418/p418Vocabulary/tree/master/html/voc/static/schema/examples/

• Repository Examples
  • Full Example by BCO-DMO
  • Minimal Example by BCO-DMO
  • See BCO-DMO homepage (view source of the page to see the schema.org JSON-LD)
• Dataset Examples
  • Full Example by BCO-DMO
  • Minimal Example by BCO-DMO

Back to top

<a id="issues"></a>

Issues

https://stackoverflow.com/questions/38243521/schema-org-contacttype-validation-issue-the-value-provided-for-office-must-be

Back to top

<a id="advanced-publishing"></a>

Advanced Publishing Techniques

<a id="advanced-publishing-category"></a>

How to publish resources for the categories/disciplines at repository services.

& How to use external vocabularies

The SWEET ontology defines a number of science disciplines and a repository could reference those, or another vocabuary's resources, by adding the vocabular to the @context attribute of the JSON-LD markup.

<a id="physical-sample-igsn"></a>

Attaching Physical Samples to a Dataset

Currently, there isn't a breat semantic property for a Dataset to distinguish the related physical samples. However, we can use the schema:hasPart property to accomplish this without too much compromise. A GitHub issue has been setup to follow this scenario. Here is the best way, so far, to link physical samples to a Dataset:

Here, we use the superclass of a Dataset, the schema:CreativeWork to also define a Physical Sample. We disambiguate the Creative Work to be a physical sample by using the GeoLink definition in the schema:additionalType field. See the schema:CreativeWork to for the additional fields available for adding to the physical sample.

NOTE: We use "IGSN" as the schema:propertyID until a canonical URI is defined by IGSN governance.

Back to top