Metadata API schemaΒΆ

The schema of the cantabular-metadata GraphQL API is described below. The types ServiceMetadata, DatasetMetadata, VariableMetadata and TableMetadata are defined in a user-supplied GraphQL schema language file at runtime. The fields in user specified types (and any nested types to which they refer directly or indirectly) may not use any arguments and may not use any scalar types apart from the builtin String type.

schema { query: Query }

type Query {
  service(
    "BCP 47 language tag specifying for which language metadata is required"
    lang: String
  ): Service

  dataset(
    "Name of dataset for which metadata is required"
    name: String!,
    lang: String
  ): Dataset

  "Digest, or hash, of all the metadata loaded into this instance"
  digest: String!
}

type Service {
  meta: ServiceMetadata!
  tables: [Table!]

  "Get the entire contents of ServiceMetadata as JSON"
  all: AllMetadata!
}

type Dataset {
  name: String!
  label: String
  description: String
  meta: DatasetMetadata!

  "Access metadata pertaining only to specific variables in the dataset"
  vars(names: [String!]!): [Variable]!

  "Get the entire contents of DatasetMetadata as JSON"
  all: AllMetadata!
}

type Variable {
  name: String!
  label: String
  description: String
  meta: VariableMetadata!

  "A map of code to label for some or all of the categories in this variable"
  catLabels: LabelsMap

  "Digest, or hash, of all the metadata in this variable"
  digest: String!

  "Get the entire contents of VariableMetadata as JSON"
  all: AllMetadata!
}

type Table {
  name: String!
  meta: TableMetadata!

  "Name of dataset containing data for this table"
  datasetName: String

  "Human-readable description for this table"
  description: String

  "Short human-readable label for this table"
  label: String

  "The variables used in this order in the query which forms this table"
  vars: [String!]!

  "All the metadata for a table"
  all: AllMetadata!
}

The name fields are what allow the metadata to be matched to data loaded into a cantabular-server service. As such:

  • The name field for a dataset must be the same as the name given to the corresponding dataset loaded into cantabular-server.

  • The name field for a variable must be the same as the name for the corresponding variable in the codebook loaded into cantabular-server for the relevant dataset.

  • The datasetName field for a service table must be the same as the name given to the corresponding dataset loaded into cantabular-server.

  • The vars field for a service table must contain names that match the name given to the variable in the codebook loaded into cantabular-server for the relevant dataset.

For more information about GraphQL, please visit the official GraphQL documentation.