database.graphql

"""
Read-only GraphQL schema for databases that store measurement and simulation
data in various formats and refer to the "metabase" for meta information like
data format specifications.

It follows best practices for
* [Global Object Identification](https://graphql.org/learn/global-object-identification/)
  as exemplified in
  [GraphQL Server Specification: Object Identification](https://relay.dev/docs/en/graphql-server-specification.html#object-identification)
  (see also [GraphQL Global Object Identification Specification](https://relay.dev/graphql/objectidentification.htm)),
  and
* [Pagination](https://graphql.org/learn/pagination/),
  by adhering to the
  [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm),
  as exemplified in
  [GraphQL Server Specification: Connections](https://relay.dev/docs/en/graphql-server-specification.html#connections).

Global object identifiers as requird by the best practice are exposed by the
property `id` and universally unique identifiers as issued by the "metabase"
are exposed by the property `uuid`. In essence, `id` is the Base64-encoded
concatenation of `uuid` and the requested locale.

For interoperability with the "metabase", implementations serve HTTP
requests as elaborated on
[Serving over HTTP](https://graphql.org/learn/serving-over-http/).

The
[Internet Engineering Task Force (IETF)](https://www.ietf.org)
is an Internet standards organization. It publishes standards in
[Request for Comments (RFC)](https://ietf.org/standards/rfcs/)
documents. They are
[searchable](https://www.rfc-editor.org/search/rfc_search.php)
and
[indexed](https://www.rfc-editor.org/rfc-index.html).
Examples are
[Hypertext Transfer Protocol (HTTP)](https://tools.ietf.org/html/rfc7231)
and
[Transport Layer Security (TLS)](https://tools.ietf.org/html/rfc8446).

The
[Internet Assigned Numbers Authority (IANA)](https://www.iana.org)
allocates and maintains unique codes and numbering systems that are used in
technical standards that drive the Internet like
[domain names](https://www.iana.org/domains),
[Internet Protocol addresses](https://www.iana.org/numbers), and
[registries](https://www.iana.org/protocols).
Examples of the last are
[HTTP status code registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml)
and
[media type registry](https://www.iana.org/assignments/media-types/media-types.xhtml).

The
[International Organization for Standardization (ISO)](https://www.iso.org)
develops and publishes
[International Standards](https://www.iso.org/standards-catalogue/browse-by-ics.html).
Examples are
[ISO 8601 Date And Time Format](https://www.iso.org/iso-8601-date-and-time-format.html)
and
[ISO 3166 Country Codes](https://www.iso.org/iso-3166-country-codes.html).

The library
[graphql-scalars](https://github.com/Urigo/graphql-scalars)
introduces custom scalar types for creating precise type-safe GraphQL schemas.
We took some inspiration from
[GitHub GraphQL API](https://docs.github.com/en/graphql).
"""
scalar Schema

schema {
  query: Query
}

"""
[RFC 4122](https://tools.ietf.org/html/rfc4122)
compliant
[non-nil](https://tools.ietf.org/html/rfc4122#section-4.1.7)
[Universally Unique Identifier (UUID)](https://tools.ietf.org/html/rfc4122#section-4.1)
string represented as 32 hexadecimal digits in five groups separated by hyphens
in the form `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, like
`"936da01f-9abd-4d9d-80c7-02af85c822a8"`. Such identifiers are not equal to
`"00000000-0000-0000-0000-000000000000"` and match the regular expression
`^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$`.
"""
scalar Uuid

"""
[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
encoded date and time string with offset from Coordinated Universal Time (UTC),
where the fraction of a second permits at most 6 digits. For example, in UTC it
may be in the form `yyyy-MM-ddTHH:mm:ss.ffffffZ`, like
`"2009-06-15T13:45:30.381739Z"`, and in local time in the form
`yyyy-MM-ddTHH:mm:ss.ffffffzzz`, like `"2009-06-15T13:45:30.381739-07:00"`.

Note that
[RFC 3339](https://tools.ietf.org/html/rfc3339)
is a profile of the ISO 8601 standard for representation of dates and times
using the Gregorian calendar.
"""
scalar DateTime

"""
[RFC 3986](https://tools.ietf.org/html/rfc3986)
and
[RFC 3987](https://tools.ietf.org/html/rfc3987)
compliant
[absolute Uniform Resource Locator (URL)](https://tools.ietf.org/html/rfc3986#section-4.3)
string with optional
[fragment identifier](https://tools.ietf.org/html/rfc3986#section-3.5).

See also
[URL Living Standard](https://url.spec.whatwg.org/#absolute-url-with-fragment-string)
and
[Identifying resources on the Web](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Identifying_resources_on_the_Web).
"""
scalar Url

"""
[BCP 47](https://tools.ietf.org/html/bcp47)
compliant
[Language Tag](https://tools.ietf.org/html/bcp47#section-2)
string like `"de-AT"`, `"sr-Latn-RS"`, `"en-US"`, or `"en-GB"`, where the language
part is essentially an
[ISO 639 Language Code](https://www.iso.org/iso-639-language-codes.html),
the script an
[ISO 15924:2004 Script Code](https://www.iso.org/standard/29546.html),
and the region an
[ISO 3166-1 Country Code](https://www.iso.org/iso-3166-country-codes.html).

Note that the
[Internet Assigned Numbers Authority (IANA)](https://www.iana.org)
maintains the
[Language Subtag Registry](https://www.iana.org/assignments/lang-subtags-templates/lang-subtags-templates.xhtml).
"""
scalar Locale

"""
[June 2018 GraphQL](http://spec.graphql.org/June2018/)
compliant
[query](http://spec.graphql.org/June2018/#sec-Language.Operations)
string without
[variables](http://spec.graphql.org/June2018/#sec-Language.Variables)
and without unnecessary white-space for the present schema.
"""
scalar GraphQlQuery

"""
[June 2018 GraphQL](http://spec.graphql.org/June2018/)
compliant
[JavaScript Object Notation (JSON)](https://tools.ietf.org/html/rfc8259)
[serialized](http://spec.graphql.org/June2018/#sec-JSON-Serialization)
[response](http://spec.graphql.org/June2018/#sec-Response)
string without unnecessary white-space for the present schema.
"""
scalar JsonGraphQlResponse

"""
[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm)
compliant
[Cursor](https://relay.dev/graphql/connections.htm#sec-Cursor)
string.
"""
scalar Cursor

"""
Non-negative integer
"""
scalar NonNegativeInt

"""
Anything
"""
scalar Any

"""
Fetch data, ask whether there is data, and search for data. Each field except
`node` accepts
- an optional timestamp to specify for which point in time the query is to be
  made and
- an optional locale to specify essentially the language of prose in the result.
Each field's value is uniquely determined by the required arguments,
timestamp, and locale throughout time.

If timestamp is not given, the moment the query is received is used. And, if
locale is not given, the default locale is used, which may differ from database
to database.
"""
type Query {
  """
  Fetch node by global object identifier as elaborated on
  [Global Object Identification](https://graphql.org/learn/global-object-identification/)
  where two nodes with identical identifiers are equal as elaborated in
  [Field stability](https://graphql.org/learn/global-object-identification/#field-stability).

  See also
  [Node root field](https://graphql.org/learn/global-object-identification/#node-root-field)
  """
  node("Global object identifier." id: ID!): Node!

  """
  Fetch data by universally unique identifier, and optional timestamp and
  locale, where all three arguments together uniquely determine the data
  throughout time.
  """
  data(
    "Data identifier."
    id: Uuid!
    "Timestamp. If not given, the moment the query is received is used."
    timestamp: DateTime
    "Locale. If not given, the default locale is used, which may differ from database to database."
    locale: Locale
  ): Data!

  """
  See `Query#data`.
  """
  calorimetricData(
    id: Uuid!
    timestamp: DateTime
    locale: Locale
  ): CalorimetricData!

  """
  See `Query#data`.
  """
  geometricData(id: Uuid!, timestamp: DateTime, locale: Locale): GeometricData!

  """
  See `Query#data`.
  """
  hygrothermalData(
    id: Uuid!
    timestamp: DateTime
    locale: Locale
  ): HygrothermalData!

  """
  See `Query#data`.
  """
  opticalData(id: Uuid!, timestamp: DateTime, locale: Locale): OpticalData!

  """
  See `Query#data`.
  """
  photovoltaicData(
    id: Uuid!
    timestamp: DateTime
    locale: Locale
  ): PhotovoltaicData!

  """
  Search for all data for which the proposition is true.

  The result is a
  [connection](https://relay.dev/graphql/connections.htm#sec-Connection-Types)
  with
  [edges](https://relay.dev/graphql/connections.htm#sec-Edge-Types)
  and
  [nodes](https://relay.dev/graphql/connections.htm#sec-Node)
  as specified in the
  [GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm),
  where the nodes are the actual data, and connection and edges are used for
  meta information and
  [pagination](https://graphql.org/learn/pagination/)
  together with the
  [forward pagination arguments](https://relay.dev/graphql/connections.htm#sec-Forward-pagination-arguments)
  `first` and `after` and the
  [backward pagination arguments](https://relay.dev/graphql/connections.htm#sec-Backward-pagination-arguments)
  `last` and `before`.

  Example:
  ```
  query {
    allData(
      where: {
        or: [
          {
            componentId: { equalTo: "810e84b4-9ebf-416c-88ea-aade848f1fdf" },
            gValue: { greaterThanOrEqualTo: 0.5 },
            not: {
              uValue: { lessThanOrEqualTo: 0.5 }
            }
          },
          {
            nearnormalHemisphericalVisibleTransmittance: {
              inClosedInterval: {
                lowerBound: 0.2,
                upperBound: 0.8
              }
            }
          }
        ]
      }
    ) {
      edges {
        node {
          uuid
        }
      }
    }
  }
  ```
  """
  allData(
    "Compound boolean expression that is true for all data being returned. If not given, a proposition that is always true is used."
    where: DataPropositionInput
    "Timestamp. If not given, the moment the query is received is used."
    timestamp: DateTime
    "Locale. If not given, the default locale is used, which may differ from database to database."
    locale: Locale
    "Maximum number of data edges after the cursor `after`."
    first: NonNegativeInt
    "Data cursor after which to return at most `first` data edges."
    after: Cursor
    "Maximum number of data edges before the cursor `before`."
    last: NonNegativeInt
    "Data cursor before which to return at most `last` data edges."
    before: Cursor
  ): DataConnection!

  """
  See `Query#allData`.
  """
  allCalorimetricData(
    where: CalorimetricDataPropositionInput
    timestamp: DateTime
    locale: Locale
    first: NonNegativeInt
    after: Cursor
    last: NonNegativeInt
    before: Cursor
  ): CalorimetricDataConnection!

  """
  See `Query#allData`.
  """
  allGeometricData(
    where: GeometricDataPropositionInput
    timestamp: DateTime
    locale: Locale
    first: NonNegativeInt
    after: Cursor
    last: NonNegativeInt
    before: Cursor
  ): GeometricDataConnection!

  """
  See `Query#allData`.
  """
  allHygrothermalData(
    where: HygrothermalDataPropositionInput
    timestamp: DateTime
    locale: Locale
    first: NonNegativeInt
    after: Cursor
    last: NonNegativeInt
    before: Cursor
  ): HygrothermalDataConnection!

  """
  See `Query#allData`.
  """
  allOpticalData(
    where: OpticalDataPropositionInput
    timestamp: DateTime
    locale: Locale
    first: NonNegativeInt
    after: Cursor
    last: NonNegativeInt
    before: Cursor
  ): OpticalDataConnection!

  """
  See `Query#allData`.
  """
  allPhotovoltaicData(
    where: PhotovoltaicDataPropositionInput
    timestamp: DateTime
    locale: Locale
    first: NonNegativeInt
    after: Cursor
    last: NonNegativeInt
    before: Cursor
  ): PhotovoltaicDataConnection!

  """
  Whether there is data for which the proposition is true at the given
  timestamp in the given locale.
  """
  hasData(
    "Compound boolean expression that is true for data being searched for."
    where: DataPropositionInput!
    "Timestamp. If not given, the moment the query is received is used."
    timestamp: DateTime
    "Locale. If not given, the default locale is used, which may differ from database to database."
    locale: Locale
  ): Boolean!

  """
  See `Query#hasData`.
  """
  hasCalorimetricData(
    where: CalorimetricDataPropositionInput
    timestamp: DateTime
    locale: Locale
  ): Boolean!

  """
  See `Query#hasData`.
  """
  hasGeometricData(
    where: GeometricDataPropositionInput
    timestamp: DateTime
    locale: Locale
  ): Boolean!

  """
  See `Query#hasData`.
  """
  hasHygrothermalData(
    where: HygrothermalDataPropositionInput
    timestamp: DateTime
    locale: Locale
  ): Boolean!

  """
  See `Query#hasData`.
  """
  hasOpticalData(
    where: OpticalDataPropositionInput
    timestamp: DateTime
    locale: Locale
  ): Boolean!

  """
  See `Query#hasData`.
  """
  hasPhotovoltaicData(
    where: PhotovoltaicDataPropositionInput
    timestamp: DateTime
    locale: Locale
  ): Boolean!

  """
  The verification code of the database that is generated by the metabase when
  an institution registers a new database. It is used by the metabase to verify
  the the institution is indeed under control of the database's GraphQL
  endpoint.

  To register and verify your database to the metabase do the following:

  1. On the metabase, sign-in as a representative of your institution.
  2. Register a new database and remember the generated verification code.
  3. Make the database's GraphQL endpoint return that code when queried for its
     verification code.
  4. Ask the metabase to verify the database.
  """
  verificationCode: String
}

"""
[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm)
and
[Global Object Identification](https://graphql.org/learn/global-object-identification/)
compliant
[Node](https://relay.dev/graphql/connections.htm#sec-Node)
interface.

See also
[Node](https://graphql.org/learn/global-object-identification/#node-interface).

Note that according to
[Field stability](https://graphql.org/learn/global-object-identification/#field-stability),
if two objects appear in a query, both implementing `Node` with identical
identifiers, then the two objects are equal. For example, for queried data, the
identifier could be a Base64-encoded concatenation of the data identifier,
which is a `Uuid`, and the requested locale.
"""
interface Node {
  """
  Base64-encoded identifier.
  """
  id: ID!
}

"""
[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm)
compliant
[PageInfo](https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo)
type.

Note that although the introspection query results on
[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm)
use the scalar type `String` for cursors, the specification of
[cursors](https://relay.dev/graphql/connections.htm#sec-Cursor)
says that a cursor is of
> a type that serializes as a `String`; this may be a `String`, a non‐null
> wrapper around a `String`, a custom scalar that serializes as a `String`, or
> a non‐null wrapper around a custom scalar that serializes as a `String`.
"""
type PageInfo {
  """
  Whether more edges exist following the set defined by the client's arguments.
  For details see
  [PageInfo: Fields](https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo.Fields).
  """
  hasNextPage: Boolean!

  """
  Whether more edges exist prior to the set defined by the clients arguments.
  For details see
  [PageInfo: Fields](https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo.Fields).
  """
  hasPreviousPage: Boolean!

  """
  Cursor corresponding to the first edge in the set defined by the client's
  arguments. For details see
  [PageInfo: Fields](https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo.Fields).
  """
  startCursor: Cursor!

  """
  Cursor corresponding to the last edge in the set defined by the client's
  arguments. For details see
  [PageInfo: Fields](https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo.Fields).
  """
  endCursor: Cursor!

  """
  Number of edges in the set defined by the client's arguments. This is equal
  to the number of nodes.
  """
  count: NonNegativeInt!
}

"""
Closed interval from lower to upper bound. Each `Float` `x` is in the interval if
and only if `x` is greater than or equal to the lower bound and less than or
equal to the upper bound. In particular, if the lower bound is equal to the
upper bound, then the interval consists of exactly one float; and, if the lower
bound is greater than the upper bound, then the interval is empty.
"""
input ClosedIntervalInput {
  """
  Lower bound.
  """
  lowerBound: Float!

  """
  Upper bound.
  """
  upperBound: Float!
}

"""
Proposition for values of type `Float`. Multiple sub-propositions are combined
conjunctively, where the conjunction of an empty set of sub-propositions is true.
"""
input FloatPropositionInput {
  """
  True for values that are equal to `equalTo`, otherwise false.
  """
  equalTo: Float

  """
  True for values that are greater than or equal to `greaterThanOrEqualTo`,
  otherwise false.
  """
  greaterThanOrEqualTo: Float

  """
  True for values that are in the closed interval `inClosedInterval`, otherwise
  false.
  """
  inClosedInterval: ClosedIntervalInput

  """
  True for values that are less than or equal to `lessThanOrEqualTo`, otherwise
  false.
  """
  lessThanOrEqualTo: Float
}

"""
Proposition for lists of values of type `Float`. Multiple sub-propositions are
combined conjunctively, where the conjunction of an empty set of
sub-propositions is true.
"""
input FloatsPropositionInput {
  """
  True if each list value satisfies the proposition `all`, otherwise false.
  """
  all: FloatPropositionInput

  """
  True if no list value satisfies the proposition `none`, otherwise false.
  """
  none: FloatPropositionInput

  """
  True if at least one list value satisfies the proposition `some`, otherwise
  false.
  """
  some: FloatPropositionInput
}

"""
Proposition for values of type `Uuid`. Multiple sub-propositions are combined
conjunctively, where the conjunction of an empty set of sub-propositions is true.
"""
input UuidPropositionInput {
  """
  True for values that are equal to `equalTo`, otherwise false.
  """
  equalTo: Uuid
}

"""
Proposition for values of type `GetHttpsResource`. Multiple sub-propositions
are combined conjunctively, where the conjunction of an empty set of
sub-propositions is true.
"""
input GetHttpsResourcePropositionInput {
  """
  True for GET HTTPS resources whose data format identifier satisfies the
  proposition `dataFormatId`, otherwise false.
  """
  dataFormatId: UuidPropositionInput

  """
  True for GET HTTPS resources whose archived files meta information satisfies
  the proposition `archivedFilesMetaInformation`, otherwise false.
  """
  archivedFilesMetaInformation: FilesMetaInformationPropositionInput
}

"""
Proposition for lists of values of type `GetHttpsResource`. Multiple
sub-propositions are combined conjunctively, where the conjunction of an empty
set of sub-propositions is true.
"""
input GetHttpsResourcesPropositionInput {
  """
  True if each list value satisfies the proposition `all`, otherwise false.
  """
  all: GetHttpsResourcePropositionInput

  """
  True if no list value satisfies the proposition `none`, otherwise false.
  """
  none: GetHttpsResourcePropositionInput

  """
  True if at least one list value satisfies the proposition `some`, otherwise
  false.
  """
  some: GetHttpsResourcePropositionInput
}

"""
Proposition for values of type `FileMetaInformation`. Multiple sub-propositions
are combined conjunctively, where the conjunction of an empty set of
sub-propositions is true.
"""
input FileMetaInformationPropositionInput {
  """
  True for file meta information whose data format identifier satisfies the
  proposition `dataFormatId`, otherwise false.
  """
  dataFormatId: UuidPropositionInput
}

"""
Proposition for lists of values of type `FileMetaInformation`. Multiple
sub-propositions are combined conjunctively, where the conjunction of an empty
set of sub-propositions is true.
"""
input FilesMetaInformationPropositionInput {
  """
  True if each list value satisfies the proposition `all`, otherwise false.
  """
  all: FileMetaInformationPropositionInput

  """
  True if no list value satisfies the proposition `none`, otherwise false.
  """
  none: FileMetaInformationPropositionInput

  """
  True if at least one list value satisfies the proposition `some`, otherwise
  false.
  """
  some: FileMetaInformationPropositionInput
}

"""
Proposition for values of type `Data`. Multiple sub-propositions are combined
conjunctively, where the conjunction of an empty set of sub-propositions is true.
"""
input DataPropositionInput {
  """
  True for data for the component with identifier `componentId`, otherwise
  false.
  """
  componentId: UuidPropositionInput

  """
  True for data for which each proposition in `and` is true, otherwise false.
  In particular, it is true if there is no proposition in `and`.
  """
  and: [DataPropositionInput!]

  """
  True for data for which the proposition `not` is false, otherwise false.
  """
  not: DataPropositionInput

  """
  True for data for which at least one proposition in `or` is true, otherwise
  false. In particular, it is false if there is no proposition in `or`.
  """
  or: [DataPropositionInput!]

  """
  True for data whose list of resources satisfies the proposition `resources`,
  otherwise false.
  """
  resources: GetHttpsResourcesPropositionInput

  """
  True for data whose list of `g` values satisfies the proposition `gValues`,
  otherwise false.
  """
  gValues: FloatsPropositionInput

  """
  True for data whose list of `u` values satisfies the proposition `uValues`,
  otherwise false.
  """
  uValues: FloatsPropositionInput

  """
  True for data whose list of `thickness` values satisfies the proposition `thicknesses`,
  otherwise false.
  """
  thicknesses: FloatsPropositionInput

  """
  True for data whose list of nearnormal hemispherical visible transmittance
  values satisfies the proposition
  `nearnormalHemisphericalVisibleTransmittances`, otherwise false.
  """
  nearnormalHemisphericalVisibleTransmittances: FloatsPropositionInput

  """
  True for data whose list of nearnormal hemispherical visible reflectance
  values satisfies the proposition
  `nearnormalHemisphericalVisibleReflectances`, otherwise false.
  """
  nearnormalHemisphericalVisibleReflectances: FloatsPropositionInput

  """
  True for data whose list of nearnormal hemispherical solar transmittance
  values satisfies the proposition
  `nearnormalHemisphericalSolarTransmittances`, otherwise false.
  """
  nearnormalHemisphericalSolarTransmittances: FloatsPropositionInput

  """
  True for data whose list of nearnormal hemispherical solar reflectance
  values satisfies the proposition
  `nearnormalHemisphericalSolarReflectances`, otherwise false.
  """
  nearnormalHemisphericalSolarReflectances: FloatsPropositionInput

  """
  True for data whose list of infrared emittance values satisfies the
  proposition `infraredEmittances`, otherwise false.
  """
  infraredEmittances: FloatsPropositionInput

  """
  True for data whose list of Color Rendering Indices satisfies the proposition
  `colorRenderingIndices`, otherwise false.
  """
  colorRenderingIndices: FloatsPropositionInput

  """
  True for data whose list of CIELAB Color Space coordinates satisfies the
  proposition `cielabColors`, otherwise false.
  """
  cielabColors: CielabColorsPropositionInput
}

"""
Proposition for values of type `CielabColor`. Multiple sub-propositions are
combined conjunctively, where the conjunction of an empty set of
sub-propositions is true.
"""
input CielabColorPropositionInput {
  """
  True for CIELAB Colors with a coordinate L* that satisfies the proposition
  `lStar`, otherwise false.
  """
  lStar: FloatPropositionInput

  """
  True CIELAB Colors with a coordinate a* that satisfies the proposition
  `aStar`, otherwise false.
  """
  aStar: FloatPropositionInput

  """
  True CIELAB Colors with a coordinate b* that satisfies the proposition
  `bStar`, otherwise false.
  """
  bStar: FloatPropositionInput
}

"""
Proposition for lists of values of type `CielabColor`. Multiple
sub-propositions are combined conjunctively, where the conjunction of an empty
set of sub-propositions is true.
"""
input CielabColorsPropositionInput {
  """
  True if each list value satisfies the proposition `all`, otherwise false.
  """
  all: CielabColorPropositionInput

  """
  True if no list value satisfies the proposition `none`, otherwise false.
  """
  none: CielabColorPropositionInput

  """
  True if at least one list value satisfies the proposition `some`, otherwise
  false.
  """
  some: CielabColorPropositionInput
}

"""
See `DataPropositionInput`.
"""
input OpticalDataPropositionInput {
  componentId: UuidPropositionInput
  and: [OpticalDataPropositionInput!]
  not: OpticalDataPropositionInput
  or: [OpticalDataPropositionInput!]
  resources: GetHttpsResourcesPropositionInput
  nearnormalHemisphericalVisibleTransmittances: FloatsPropositionInput
  nearnormalHemisphericalVisibleReflectances: FloatsPropositionInput
  nearnormalHemisphericalSolarTransmittances: FloatsPropositionInput
  nearnormalHemisphericalSolarReflectances: FloatsPropositionInput
  infraredEmittances: FloatsPropositionInput
  colorRenderingIndices: FloatsPropositionInput
  cielabColors: CielabColorsPropositionInput
}

"""
See `DataPropositionInput`.
"""
input CalorimetricDataPropositionInput {
  componentId: UuidPropositionInput
  and: [CalorimetricDataPropositionInput!]
  not: CalorimetricDataPropositionInput
  or: [CalorimetricDataPropositionInput!]
  resources: GetHttpsResourcesPropositionInput
  gValues: FloatsPropositionInput
  uValues: FloatsPropositionInput
}

"""
See `DataPropositionInput`.
"""
input GeometricDataPropositionInput {
  componentId: UuidPropositionInput
  and: [GeometricDataPropositionInput!]
  not: GeometricDataPropositionInput
  or: [GeometricDataPropositionInput!]
  resources: GetHttpsResourcesPropositionInput
  thicknesses: FloatsPropositionInput
}

"""
See `DataPropositionInput`.
"""
input HygrothermalDataPropositionInput {
  componentId: UuidPropositionInput
  and: [HygrothermalDataPropositionInput!]
  not: HygrothermalDataPropositionInput
  or: [HygrothermalDataPropositionInput!]
  resources: GetHttpsResourcesPropositionInput
}

"""
See `DataPropositionInput`.
"""
input PhotovoltaicDataPropositionInput {
  componentId: UuidPropositionInput
  and: [PhotovoltaicDataPropositionInput!]
  not: PhotovoltaicDataPropositionInput
  or: [PhotovoltaicDataPropositionInput!]
  resources: GetHttpsResourcesPropositionInput
}

"""
Materialized connection from somewhere to data to paginate data using opaque
cursors as elaborated in the best practice
[Pagination](https://graphql.org/learn/pagination/)
and the specification
[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm),
see in particular
[Complete Connection Model](https://graphql.org/learn/pagination/#complete-connection-model)
and
[Connection Types](https://relay.dev/graphql/connections.htm#sec-Connection-Types).
"""
type DataConnection {
  """
  Edges to data nodes that expose opaque cursors for pagination.
  """
  edges: [DataEdge!]!

  """
  Total number of data edges (and nodes) of which a slice is `edges` (and
  `nodes`). Note that the number of edges (and nodes) of the present slice is
  `pageInfo.count`.
  """
  totalCount: NonNegativeInt!

  """
  Information about the present slice of all data edges (and nodes).
  """
  pageInfo: PageInfo!

  """
  Timestamp at or for which the connection, its edges and nodes are returned.
  In case no timestamp was given as argument, this is the moment in time the
  query was made. Otherwise, it is the given timestamp. All data edges and
  nodes are fetched as they were at this timestamp.
  """
  timestamp: DateTime!
}

"""
Materialized edge from somewhere to data to paginate data using opaque
cursors as elaborated in the best practice
[Pagination](https://graphql.org/learn/pagination/)
and the specification
[GraphQL Cursor Connections Specification](https://relay.dev/graphql/connections.htm),
see in particular
[Complete Connection Model](https://graphql.org/learn/pagination/#complete-connection-model)
and
[Edge Types](https://relay.dev/graphql/connections.htm#sec-Edge-Types).
"""
type DataEdge {
  """
  Opaque
  [cursor](https://relay.dev/graphql/connections.htm#sec-Cursor)
  that designates the present edge for pagination.
  """
  cursor: Cursor!

  """
  Data node the edge points to.
  """
  node: Data!
}

"""
See `DataConnection`.
"""
type OpticalDataConnection {
  edges: [OpticalDataEdge!]!
  pageInfo: PageInfo!
  timestamp: DateTime!
}

"""
See `DataEdge`.
"""
type OpticalDataEdge {
  cursor: Cursor!
  node: OpticalData!
}

"""
See `DataConnection`.
"""
type HygrothermalDataConnection {
  edges: [HygrothermalDataEdge!]!
  pageInfo: PageInfo!
  timestamp: DateTime!
}

"""
See `DataEdge`.
"""
type HygrothermalDataEdge {
  cursor: Cursor!
  node: HygrothermalData!
}

"""
See `DataConnection`.
"""
type PhotovoltaicDataConnection {
  edges: [PhotovoltaicDataEdge!]!
  pageInfo: PageInfo!
  timestamp: DateTime!
}

"""
See `DataEdge`.
"""
type PhotovoltaicDataEdge {
  cursor: Cursor!
  node: PhotovoltaicData!
}

"""
See `DataConnection`.
"""
type CalorimetricDataConnection {
  edges: [CalorimetricDataEdge!]!
  pageInfo: PageInfo!
  timestamp: DateTime!
}

"""
See `DataConnection`.
"""
type GeometricDataConnection {
  edges: [GeometricDataEdge!]!
  pageInfo: PageInfo!
  timestamp: DateTime!
}

"""
See `DataEdge`.
"""
type CalorimetricDataEdge {
  cursor: Cursor!
  node: CalorimetricData!
}

"""
See `DataEdge`.
"""
type GeometricDataEdge {
  cursor: Cursor!
  node: GeometricData!
}

"""
Measured, simulated, or calculated data.

The data identifier identifies the data modulo patches and locale, together
with timestamp only modulo locale, together with locale only modulo patches,
and together with both all data. In the last case, in particular, the order of
any list values of (sub-)fields is fix.

For non-patch versions a new data identifier is needed.

Note that the term 'patch' is used in the sense of
[Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
"""
interface Data {
  """
  Identifier, which together with timestamp uniquely identifies data and patch
  version (within the database).
  """
  uuid: Uuid!

  """
  Timestamp that designates the patch version. For example, correction of some
  grammatical error in the description results in a new patch version
  designated by a new timestamp, or adding an approval by some stakeholder.
  """
  timestamp: DateTime!

  """
  Component identifier issued by the metabase. The components's meta data can
  be obtained by sending the GraphQL query
  `component(componentId: ..., timestamp: ...) { ... }`
  to the metabase.
  """
  componentId: Uuid!

  """
  Name
  """
  name: String

  """
  Description for humans
  """
  description: String

  """
  Critical information to avoid mistakes due to data misinterpretation.
  """
  warnings: [String!]!

  """
  Creator identifier issued by the metabase. The creator's meta data can be
  obtained by sending the GraphQL query
  `stakeholder(stakeholderId: ..., timestamp: ...) { ... }`
  to the metabase.
  """
  creatorId: Uuid!

  """
  Creation timestamp, designating when the present data set was created, for
  example, after completion of a measurement, simulation, or calculation.
  """
  createdAt: DateTime!

  """
  Method that was applied to create this data set.
  """
  appliedMethod: AppliedMethod!

  """
  Approvals by stakeholders in the form of GnuPG signatures. See the type
  `Approval` for details on how to verify data and approvals.
  """
  approvals: [DataApproval!]!

  """
  Multiple HTTP resources with meta information of the actual data requestable
  through the protocol HTTP over TLS, in short, HTTPS, with `GET` requests. The
  first resource's data is the result of applying the method `appliedMethod`.
  The other resources' data is the result of applying some conversion method or
  a chain of such methods to the first resource's data. Detailed information
  about which conversion method applied to which data resulted in which other
  data is recorded in the tree `resourceTree` with the root `resourceTree.root`
  and the non-root vertices `resourceTree.nonRootVertices`.

  Note that all resources describe the same data only in different formats.
  """
  resources: [GetHttpsResource!]!

  """
  Multiple HTTP resources organized as tree with meta information of the actual
  data requestable through the protocol HTTP over TLS, in short, HTTPS, with
  `GET` requests. The root-resource's data is the result of applying the method
  `appliedMethod`. Each non-root-resource's data is the result of applying
  a specified conversion method to its parent resource's data.

  Note that all resources describe the same data only in different formats.
  """
  resourceTree: GetHttpsResourceTree!

  """
  Approval by the database of the result without the field `approval` itself.
  """
  approval: ResponseApproval!

  """
  Locale of text
  """
  locale: Locale!
}

"""
The CIELAB Color Space is used to define a color. It has three rectangular color coordinates, L* (lStar), a* (aStar) and b* (bStar).
"""
type CielabColor {
  """
  The coordinate L* (lStar) defines the lightness of the color.
  """
  lStar: Float!

  """
  The coordinate a* (aStar) defines the color between green and red.
  """
  aStar: Float!

  """
  The coordinate b* (bStar) defines the color between blue and yellow.
  """
  bStar: Float!
}

type OpticalData implements Node & Data {
  id: ID!
  uuid: Uuid!
  timestamp: DateTime!
  locale: Locale!
  databaseId: Uuid!
  componentId: Uuid!
  name: String
  description: String
  warnings: [String!]!
  creatorId: Uuid!
  createdAt: DateTime!
  appliedMethod: AppliedMethod!
  resources: [GetHttpsResource!]!
  resourceTree: GetHttpsResourceTree!
  approvals: [DataApproval!]!
  approval: ResponseApproval!

  """
  Mirrored nearnormal hemispherical visible transmittance values that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  nearnormalHemisphericalVisibleTransmittances: [Float!]!
  """
  Mirrored nearnormal hemispherical visible reflectance values that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  nearnormalHemisphericalVisibleReflectances: [Float!]!

  """
  Mirrored nearnormal hemispherical solar transmittance values that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  nearnormalHemisphericalSolarTransmittances: [Float!]!

  """
  Mirrored nearnormal hemispherical solar reflectance values that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  nearnormalHemisphericalSolarReflectances: [Float!]!

  """
  Mirrored infrared emittance values that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  infraredEmittances: [Float!]!

  """
  Mirrored values for the Color Rendering Index that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  colorRenderingIndices: [Float!]!

  """
  Mirrored values for the coordinates in the CIELAB Color Space that occur in the data. If some or all of those values do not occur verbatim in the data, they need not occur in the list, even if they can be calculated based on the data.
  """
  cielabColors: [CielabColor!]!
}

type CalorimetricData implements Node & Data {
  id: ID!
  uuid: Uuid!
  timestamp: DateTime!
  locale: Locale!
  databaseId: Uuid!
  componentId: Uuid!
  name: String
  description: String
  warnings: [String!]!
  creatorId: Uuid!
  createdAt: DateTime!
  appliedMethod: AppliedMethod!
  resources: [GetHttpsResource!]!
  resourceTree: GetHttpsResourceTree!
  approvals: [DataApproval!]!
  approval: ResponseApproval!

  """
  Mirrored `g` values that occur in the data
  """
  gValues: [Float!]!

  """
  Mirrored `u` values that occur in the data
  """
  uValues: [Float!]!
}

type GeometricData implements Node & Data {
  id: ID!
  uuid: Uuid!
  timestamp: DateTime!
  locale: Locale!
  databaseId: Uuid!
  componentId: Uuid!
  name: String
  description: String
  warnings: [String!]!
  creatorId: Uuid!
  createdAt: DateTime!
  appliedMethod: AppliedMethod!
  resources: [GetHttpsResource!]!
  resourceTree: GetHttpsResourceTree!
  approvals: [DataApproval!]!
  approval: ResponseApproval!

  """
  Mirrored `thickness` values that occur in the data
  """
  thicknesses: [Float!]!
}

type HygrothermalData implements Node & Data {
  id: ID!
  uuid: Uuid!
  timestamp: DateTime!
  locale: Locale!
  databaseId: Uuid!
  componentId: Uuid!
  name: String
  description: String
  warnings: [String!]!
  creatorId: Uuid!
  createdAt: DateTime!
  appliedMethod: AppliedMethod!
  resources: [GetHttpsResource!]!
  resourceTree: GetHttpsResourceTree!
  approvals: [DataApproval!]!
  approval: ResponseApproval!
}

type PhotovoltaicData implements Node & Data {
  id: ID!
  uuid: Uuid!
  timestamp: DateTime!
  locale: Locale!
  databaseId: Uuid!
  componentId: Uuid!
  name: String
  description: String
  warnings: [String!]!
  creatorId: Uuid!
  createdAt: DateTime!
  appliedMethod: AppliedMethod!
  resources: [GetHttpsResource!]!
  resourceTree: GetHttpsResourceTree!
  approvals: [DataApproval!]!
  approval: ResponseApproval!
}

"""
Applied method, that is the application of a method with fixed arguments to
specific source data.
"""
type AppliedMethod {
  """
  Method identifier of method that was applied by the creator on the source
  data. The method's meta data can be obtained by sending the GraphQL query
  `method(methodId: ..., timestamp: ...) { ... }`
  to the metabase.
  """
  methodId: Uuid!

  """
  Named arguments to configure the method.
  - For each parameter required by the method, there is exactly one argument in
    the list.
  - Each argument in the list corresponds to an optional or required parameter
    of the method.
  - Each two distinct arguments in the list have different names.
  """
  arguments: [NamedMethodArgument!]!

  """
  Named data sources to which the method was applied.
  - For each source required by the method, there is exactly one source in the
    list.
  - Each source in the list corresponds to an optional or required source of
    the method.
  - Each two distinct sources in the list have different names.
  """
  sources: [NamedMethodSource!]!
}

"""
Applied conversion method to exactly one named source, namely the tree-vertex's
parent resource.
"""
type ToTreeVertexAppliedConversionMethod {
  """
  Method identifier of conversion method that was applied by the creator on the
  source data. The method's meta data can be obtained by sending the GraphQL
  query
  `method(methodId: ..., timestamp: ...) { ... }`
  to the metabase.
  """
  methodId: Uuid!

  """
  Named arguments to configure the conversion method.
  - For each parameter required by the method, there is exactly one argument in
    the list.
  - Each argument in the list corresponds to an optional or required parameter
    of the method.
  - Each two distinct arguments in the list have different names.
  """
  arguments: [NamedMethodArgument!]!

  """
  Name of the named data source of the conversion method whose value is the
  tree-vertex's parent resource. The conversion method requires at least one
  named source and a value for one of these sources is given.
  """
  sourceName: String!
}

"""
Named argument of a method.
"""
type NamedMethodArgument {
  """
  Name
  """
  name: String!

  """
  Method argument value.
  """
  value: Any!
}

"""
Named data source of a method.
"""
type NamedMethodSource {
  """
  Name
  """
  name: String!

  """
  Method source as cross-database data reference.
  """
  value: CrossDatabaseDataReference!
}

"""
Cross-database data reference.
"""
type CrossDatabaseDataReference {
  """
  Identifier of the referenced data.
  """
  dataId: Uuid!

  """
  Timestamp of referenced data to designate the data's version.
  """
  dataTimestamp: DateTime!

  """
  Kind of the referenced data.
  """
  dataKind: DataKind!

  """
  Identifier of the database that manages the referenced data.
  """
  databaseId: Uuid!
}

"""
Data kind, either calorimetric, hygrothermal, optical, or photovoltaic.
"""
enum DataKind {
  CALORIMETRIC_DATA
  HYGROTHERMAL_DATA
  OPTICAL_DATA
  PHOTOVOLTAIC_DATA
}

"""
Open-ended data and time range.
"""
type OpenEndedDateTimeRange {
  """
  From beginning of time represented by `null`, or some date and time.
  """
  from: DateTime

  """
  Until some date and time, or end of time represented by `null`.
  """
  until: DateTime
}

"""
Approval with
[GnuPG](https://www.gnupg.org)
signature.

To verify an approval,
1. install [GnuPG](https://www.gnupg.org),
2. save the approved response in a file `response.json`,
3. save the ASCII-armored signature in a file `response.json.asc`,
4. * retrieve the public key for the given fingerprint from the metabase's
     keyserver by running
     `gpg --keyserver hkps://keyserver.buildingenvelopedata.org --recv-keys <FINGERPRINT>`
     (or
     `gpg --fetch-keys https://buildingenvelopedata.org/gnuPgKey/<FINGERPRINT>.asc`)
     and make sure that the key belongs to the approver, was allowed for
     signing, and was valid at a given timestamp by sending a request of the
     form
     ```
     database(databaseId: ..., timestamp: <TIMESTAMP>) {
       hasGnuPgKey(fingerprint: <FINGERPRINT>, status: ALLOWED, valid: true)
     }
     ```
     or
     ```
     stakeholder(stakeholderId: ..., timestamp: <TIMESTAMP>) {
       hasGnuPgKey(fingerprint: <FINGERPRINT>, status: ALLOWED, valid: true)
     }
     ```
   * or retrieve the allowed-for-signing and valid-at-the-given-time key from
     the metabase's GraphQL endpoint by sending a request of the form
     ```
     database(databaseId: ..., timestamp: <TIMESTAMP>) {
       gnuPgKey(fingerprint: <FINGERPRINT>, status: ALLOWED, valid: true)
     }
     ```
     or
     ```
     stakeholder(stakeholderId: ..., timestamp: <TIMESTAMP>) {
       gnuPgKey(fingerprint: <FINGERPRINT>, status: ALLOWED, valid: true)
     }
     ```
     save the ASCII-armored key in a file `my.gpg.asc`, and import it by running
     `gpg --import ./my.gpg.asc`.
   where `<TIMESTAMP>` is the timestamp at which the approval was created (for
   response approvals this is the timestamp of the response).
5. verify the signature with the public key by running
   `gpg --verify response.json.asc response.json`.

To create an approval,
1. install [GnuPG](https://www.gnupg.org),
2. create a master key by running
   `gpg --full-generate-key`,
   selecting option `3. DSA (sign only)`,
   choosing the keysize `2048`,
   setting the validity `2y = key expires in 2 years`, and
   answering all subsequent questions in particular adding a strong passphrase.
3. create a signing subkey by running
   `gpg --edit-key <YOUR_EMAIL_ADDRESS>`,
   entering the command `addkey`
   selecting option `(3) DSA (sign only)`,
   choosing the keysize `2048`,
   setting the validity `2y = key expires in 2 years`, and
   answering all subsequent questions, and
   entering the command `save`.
4. list your keys with fingerprints by running
   `gpg --list-keys --with-subkey-fingerprint <YOUR_EMAIL_ADDRESS>`.
5. adds it your signing key to the metabase and its keyserver (both are
   coupled and one cannot be done without the other) either with the GraphQL
   mutation
   ```
   mutation {
     sendKeys(input: {
       asciiArmoredKeys: <ASCII_ARMORED_KEYS>
       keyFingerprint: <SIGNING_KEY_FINGERPRINT>
     }) { }
   }
   ```
   where `<ASCII_ARMORED_KEYS>` is the standard output of running
   `gpg --export --armor --output - <SIGNING_KEY_FINGERPRINT>`,
   or by running
   `gpg --keyserver hkps://keyserver.buildingenvelopedata.org --send-keys <SIGNING_KEY_FINGERPRINT>`.
6. save the response to be approved in a file `response.json`,
7. compute the signature and write it to `response.json.asc` by running
   `gpg --detach-sig --armor --local-user <SIGNING_KEY_FINGERPRINT> response.json`, and
8. add the signature as approval to the database through its interface.

Best practices for managing GnuPG keys within an institution:
* In the metabase, each institution has at least one representative and the
  institution's GnuPG keys are but the keys of all its representatives.
* Each representative of an institution within the metabase who is allowed to
  approve data for its institution adds its signing key to the metabase and its
  keyserver (both are coupled and one cannot be done without the other) either
  with the GraphQL mutation
  ```
  mutation {
    sendKeys(input: {
      asciiArmoredKeys: <ASCII_ARMORED_KEYS>
      keyFingerprint: <SIGNING_KEY_FINGERPRINT>
    }) { }
  }
  ```
  where `<ASCII_ARMORED_KEYS>` is the standard output of running
  `gpg --export --armor --output - <SIGNING_KEY_FINGERPRINT>`,
  or by running
  `gpg --keyserver hkps://keyserver.buildingenvelopedata.org --send-keys <SIGNING_KEY_FINGERPRINT>`.
* When a representative's signing subkey is compromised she revokes it as
  described in
  [Revoking key components](https://www.gnupg.org/gph/en/manual.html#AEN305)
  and publishes the revocation either with the corresponding GraphQL mutation
  ```
  mutation {
    sendKeys(input: {
      asciiArmoredKeys: <ASCII_ARMORED_KEYS>
      keyFingerprint: <SIGNING_KEY_FINGERPRINT>
    }) { }
  }
  ```
  where `<ASCII_ARMORED_KEYS>` is the standard output of running
  `gpg --export --armor --output - <SIGNING_KEY_FINGERPRINT>`,
  or by running
  `gpg --keyserver hkps://keyserver.buildingenvelopedata.org --send-key <SIGNING_KEY_FINGERPRINT>`.
* When a representative leaves a company or is no longer allowed to approve data,
  the metabase is informed about that with the GraphQL mutation
  ```
  mutation {
    removeInstitutionRepresentative(input: {
      userId: <USER_ID>
      institutionId: <INSTITUTION_ID>
    }) { }
  }
  ```
  or
  ```
  mutation {
    forbidInstitutionRepresentativeToSignData(input: {
      userId: <USER_ID>
      institutionId: <INSTITUTION_ID>
    }) { }
  }
  ```

Best practices for accepting approvals by databases:
* Check that the fingerprint belongs to a non-revoked and valid GnuPG key of an
  active representative of an institution who is allowed to make signatures for
  that institution.
* Check that the query contains all necessary fields and sub-fields and
  specifies a timestamp.
* Check that the response is the result of the given query.
* Check that the signature is valid for the given response.

Note that GnuPG is compliant with
[OpenPGP Message Format](https://tools.ietf.org/html/rfc4880).

For an introduction to GnuPG consult
[The GNU Privacy Handbook](https://www.gnupg.org/gph/en/manual.html)
or the article series
[Getting started with GPG (GnuPG)](https://www.redhat.com/sysadmin/getting-started-gpg),
[How to create GPG keypairs](https://www.redhat.com/sysadmin/creating-gpg-keypairs), and
[Digital signatures with GnuPG](https://www.redhat.com/sysadmin/digital-signatures-gnupg).
"""
interface Approval {
  """
  Creation timestamp
  """
  timestamp: DateTime!

  """
  Detached ASCII-armored GnuPG signature of the GraphQL query response.

  With the query response saved in the file `response.json`, the signature can
  be computed and written to `response.json.asc` by running
  `gpg --detach-sig --armor response.json`
  (to write it to standard output instead, add the option `--output -`). And,
  the signature can be verified by running
  `gpg --verify response.json.asc response.json`.
  Note that to compute a signature you need a GnuPG signing private key in your
  key ring and to verify a signature you need the GnuPG signing public key
  whose corresponding private key was used to compute the signature.
  """
  signature: String!

  """
  Fingerprint of the GnuPG signing key used to compute the signature.

  The key's fingerprint, long identifier, and short identifier are related as
  in the follow example:
  * fingerprint: 0D69 E11F 12BD BA07 7B37  26AB 4E1F 799A A4FF 2279
  * long id:                                    4E1F 799A A4FF 2279
  * short id:                                             A4FF 2279
  Fingerprints can be used anywhere where an identifier is expected. For
  security reasons it is used instead of long and short identifier. Its only
  disadvantage is that it is less practical for manual human use.
  """
  keyFingerprint: String!

  """
  GraphQL query whose response is signed. The query includes the argument
  `timestamp`, for example,
  ```
  opticalData(opticalDataId: ..., timestamp: ...) { ... }
  ```
  as otherwise it is not reproducible. It does neither include other data
  approvals by third parties nor the response approval by the database.  All
  other fields and sub-fields of this GraphQL schema at the time given by
  `timestamp` are included. Despite these restrictions specifying the query
  explicitely is necessary because approvals shall not become invalid when the
  GraphQL schema changes.
  """
  query: GraphQlQuery!

  """
  JSON serialized GraphQL response that is signed.

  With the response put in the file `response.json`, the GnuPG signature put in
  the file `response.json.asc`, and the GnuPG public key of the approver added
  to the GnuPG key ring, the signature can be verified by running
  `gpg --verify response.json.asc response.json`.

  To compare the response `response.json` and another response `another.json`,
  run the command
  ```
  diff --side-by-side --suppress-common-lines \
    <(jq --sort-keys --monochrome-output . response.json) \
    <(jq --sort-keys --monochrome-output . another.json)
  ```
  in a
  [Bourne-again shell (Bash)](https://www.gnu.org/software/bash/),
  see
  [Faster and simpler with the command line: deep-comparing two 5GB JSON files 3X faster by ditching the code](https://genius.engineering/faster-and-simpler-with-the-command-line-deep-comparing-two-5gb-json-files-3x-faster-by-ditching-the-code/)
  and
  [Using jq or alternative command line tools to compare JSON files](https://stackoverflow.com/questions/31930041/using-jq-or-alternative-command-line-tools-to-compare-json-files/37175540#37175540).

  Comparing responses is necessary to verify that the data `another.json` you
  received in a query that includes this approval matches the approved data.
  Which is of course the case if all involved organizations are trustworthy.
  However, verified signatures and matching responses together prove data
  integrity (at least if private keys used to make the signatures in the first
  place are not compromised).
  """
  response: JsonGraphQlResponse!
}

"""
Approval of data by third party with GnuPG signature that is created at some
point in time. It becomes invalid when the approved data changes, even if the
change is but a spelling-error correction in meta data like the description.
In that case, the third party needs to re-create its approval.

Steps to approve data:
1. An institution adds data to a database.
2. Some institution (may be the same) queries the data with a GraphQL query.
3. The latter institution reviews the data and, if correct, signs it with one
   of its GnuPG signing keys.
4. The institution adds its approval of the data to the database.

Storing the GraphQL query with the signature is necessary because it needs to be
known exactly which JSON data was signed.

Note that the query to be signed only includes paths that are part of the data
and not part of some associates, which are actually all paths in the present
GraphQL schema. However, the actual GraphQL schema of the database is in
general an extension of the present GraphQL schema and may have paths to some
associates like data format specifics of HTTP resources that it may fetch from
the "metabase" and provides for convenience. These specifics should not be
sigend as a change of, for example, the data format description would
invalidate the signature although the data itself did not change.
"""
type DataApproval implements Approval {
  timestamp: DateTime!
  signature: String!
  keyFingerprint: String!
  query: GraphQlQuery!
  response: JsonGraphQlResponse!

  """
  Approver identifier issued by the metabase. The approver's meta data can be
  obtained by sending the GraphQL query
  `stakeholder(stakeholderId: ..., timestamp: ...) { ... }`
  to the metabase.
  """
  approverId: Uuid!
}

"""
Approval of response by database with
[GnuPG](https://www.gnupg.org)
signature.
"""
type ResponseApproval implements Approval {
  timestamp: DateTime!
  signature: String!
  keyFingerprint: String!
  query: GraphQlQuery!
  response: JsonGraphQlResponse!
}

"""
HTTP resource with meta information requestable through the protocol
[HTTP over TLS](https://tools.ietf.org/html/rfc2818)
with `GET` requests. The protocol is colloquially called Hypertext Transfer
Protocol Secure (HTTPS) and uses
[Transport Layer Security (TLS)](https://tools.ietf.org/html/rfc8446)
to secure
[Hypertext Transfer Protocol (HTTP)](https://tools.ietf.org/html/rfc7231)
connections over the internet.

If an HTTP `GET` request of the resource is
[successful](https://tools.ietf.org/html/rfc7231#section-6.3)
with
[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6)
[200](https://tools.ietf.org/html/rfc7231#section-6.3.1),
the response message body is the resource's content. Otherwise, there is some
issue that can be identified and hopefully resolved by examining the status
code.

Note that the
[Internet Assigned Numbers Authority (IANA)](https://www.iana.org)
maintains the
[HTTP status code registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
See also
[HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).
"""
type GetHttpsResource {
  """
  Description
  """
  description: String

  """
  Hash value of sucessful HTTP response message body with
  [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6)
  [200](https://tools.ietf.org/html/rfc7231#section-6.3.1)
  computed with
  Secure Hash Algorithm 256 (SHA-256)
  as described in the
  [United States's Federal Information Processing Standard 180-4 (FIPS 180-4)](https://csrc.nist.gov/publications/detail/fips/180/4/final)
  by the
  [National Institute of Standards and Technology (NIST)](https://www.nist.gov).
  See also
  [RFC 6234](https://tools.ietf.org/html/rfc6234).

  In Linux,
  1. install
     [Coreutils - GNU core utilities](https://www.gnu.org/software/coreutils/),
     to get the command-line tool
     [`sha256sum`](http://www.gnu.org/software/coreutils/sha256sum), and
  2. save the message body in a file, say `message.body`.

  Then, to compute the hash value,
  3. run the command `sha256sum message.body`, which prints the hash value to
     standard output.

  And, to check the hash value,
  4. run the command `echo '<HASH_VALUE>  message.body' | sha256sum --check`,
     where `<HASH_VALUE>` needs to be replaced by the hash value. Note that
     there are two spaces between `<HASH_VALUE>` and `message.body`.

  In Mac OS X, the command-line tool `shasum` comes pre-installed and can be
  used instead of `sha256sum` by adding the option `--algorithm 256` that is
  by literally replacing `sha256sum` in the above commands by
  `shasum --algorithm 256`.

  In Windows,
  1. install
     [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell)
  2. save the message body in a file, say `message.body`.
  3. open a PowerShell window, for example, by pressing `WIN+R`,
     typing in `powershell`, and pressing `<enter>`, and
  4. change directory to the folder with the saved files.

  Then, to compute the hash value,
  5. run the command
     `(Get-FileHash -Algorithm SHA256 .\message.body).Hash`,
     which prints the hash value. For details see the documentation
     [Get-FileHash](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/get-filehash).

  And, to check the hash value,
  6. save the message body's hash in a file, say `message.body.sha`,
  7. run the command
     `(Get-FileHash -Algorithm SHA256 .\message.body).Hash -eq (Get-Content .\message.body.sha).split(" ")[0].ToUpper()`,
     which prints `True` on success.

  In case [OpenSSL](https://www.openssl.org) is installed, to compute the hash
  value, you may also run `openssl dgst -sha256 message.body`.
  """
  hashValue: String!

  """
  Locator with scheme `https` to be used with protocol
  [HTTP over TLS](https://tools.ietf.org/html/rfc2818).
  """
  locator: Url!

  """
  Identifier of data format of successful HTTP response message body with
  [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6)
  [200](https://tools.ietf.org/html/rfc7231#section-6.3.1).
  The identifier is issued by the metabase. The format's meta data can be
  obtained by sending the GraphQL query
  `dataFormat(dataFormatId: ..., timestamp: ...) { ... }`
  to the metabase.

  The data format consists of a
  [media type](https://www.iana.org/assignments/media-types/media-types.xhtml)
  and additional information to unambiguously identify the specific format and
  to locate the format specification.

  In case of an
  [archive format](https://en.wikipedia.org/wiki/Archive_file),
  for each archived file (that is, each file in the archive), meta information
  like its data format is specified in `archivedFilesMetaInformation`. The file
  and directory names in the archive match the regular expression
  `^[0-9a-z-._]$` for reasons elaborated in `FileMetaInformation#path`. See
  also
  [List of archive formats](https://en.wikipedia.org/wiki/List_of_archive_formats).
  """
  dataFormatId: Uuid!

  """
  Archived files meta information with relative paths from the archive root and
  data format specifications. In case the data format is not an archive, the
  list is empty. Otherwise, in case the data format is an, for our purposes,
  underspecified archive format like
  [7-Zip](https://www.7-zip.org)
  with an a priori unknown internal structure, for each archived file, there is
  exactly one list entry.

  Note that the
  [extensions of file names](https://en.wikipedia.org/wiki/Filename_extension)
  in the archive are not sufficient as data format because file extensions are
  not standardized and not sufficiently precise. For example, the extension
  `docx` is commonly used for documents with the media type
  [application/vnd.openxmlformats-officedocument.wordprocessingml.document](https://www.iana.org/assignments/media-types/application/vnd.openxmlformats-officedocument.wordprocessingml.document)
  but does not tell which exact version of the standard is meant.
  """
  archivedFilesMetaInformation: [FileMetaInformation!]!
}

"""
Multiple HTTP resources organized as tree with meta information of the actual
data requestable through the protocol HTTP over TLS, in short, HTTPS, with
`GET` requests. Each vertex specifies
* its vertex identifier (unique among the tree vertices), and
* its HTTP resource.
Each non-root vertex also specifies
* its parent vertex's identifier, and
* an applied conversion method with its parent vertex's identifier as source,
where indeed the non-root-resource's data is the result of applying the
conversion method to its parent resource's data.

The root vertex is in the field `root` and non-root resource vertices are in
the field `nonRootVertices`.

Note that all resources describe the same data only in different formats.
"""
type GetHttpsResourceTree {
  """
  Root resource vertex.
  """
  root: GetHttpsResourceTreeRoot!

  """
  Non-root resource vertices in breadth-first order starting from, but not
  including, the root vertex.

  By traversing the tree from the root at each vertex it is clear how the
  vertex's data was obtained from the parent's data and by remembering or
  composing the chain of applied conversion methods how the vertex's data was
  obtained from the root's data.
  """
  nonRootVertices: [GetHttpsResourceTreeNonRootVertex!]!
}

"""
A root or non-root resource is the result of some measurement or simulation, or
of applying some conversion method to its parent resource. Its child resources
are the results of applying conversion methods to it, the child resources of
its child resources are the results of applying conversion methods to the child
resources, and so forth. The applied conversion methods are specified in the
child resource vertices.
"""
interface GetHttpsResourceTreeVertex {
  """
  Vertex identifier unique among the tree vertices. It is used to set-up edges,
  that is, parent/child relationships, in the flattened tree structure.
  """
  vertexId: ID!

  """
  Resource
  """
  value: GetHttpsResource!
}

"""
A root resource is the direct result of some measurement or simulation.
"""
type GetHttpsResourceTreeRoot implements GetHttpsResourceTreeVertex {
  vertexId: ID!
  value: GetHttpsResource!
}

"""
A non-root resource is the result of applying some conversion method to its
parent resource.
"""
type GetHttpsResourceTreeNonRootVertex implements GetHttpsResourceTreeVertex {
  vertexId: ID!
  value: GetHttpsResource!

  """
  Identifier of parent resource vertex. This vertex's resource data it obtained by
  applying the conversion method to its parent resource data.
  """
  parentId: ID!

  """
  Conversion method applied to the parent resource to obtain the present
  vertex's resource. The parent resource is identified by the vertex identifier
  `appliedConversionMethod.source.value`.
  """
  appliedConversionMethod: ToTreeVertexAppliedConversionMethod!
}

"""
File meta information.
"""
type FileMetaInformation {
  """
  Relative file path, where
  * the string-serialized
    [POSIX-style path](https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap03.html#tag_03_266)
    is obtained by prepending the string `./` and joining all components with the
    forward slash `/`, see also,
    [IEEE/Open Group 1003.1-2017 - IEEE Standard for Information Technology--Portable Operating System Interface (POSIX(TR)) Base Specifications, Issue 7](https://standards.ieee.org/standard/1003_1-2017.html),
    and
  * the string-serialized
    [Windows-style path](https://docs.microsoft.com/en-us/dotnet/standard/io/file-path-formats)
    is obtained by prepending the
    string `.\` and joining all components with the backward slash `\`, see also
    [Naming Files, Paths, and Namespaces](https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file).

  Each path component is a valid file or directory name in popular operating
  systems like various Linux distributions, Windows, and Mac OS X, and it is
  usable. Because of various idiosyncrasies of different file systems and
  command-line interpreters, each component matches the regular expression
  `^[a-z0-9-._]+$`. For some reasons see
  [Answer 1](https://superuser.com/questions/358855/what-characters-are-safe-in-cross-platform-file-names-for-linux-windows-and-os/358861#358861)
  and
  [Answer 2](https://superuser.com/questions/358855/what-characters-are-safe-in-cross-platform-file-names-for-linux-windows-and-os/748264#748264)
  to the dated question
  [What characters are safe in cross-platform file names for Linux, Windows and OS-X](https://superuser.com/questions/358855/what-characters-are-safe-in-cross-platform-file-names-for-linux-windows-and-os),
  and also
  [Best Practices for Filenames on the Web](https://www.surrealcms.com/blog/best-practices-for-filenames-on-the-web.html).
  """
  path: [String!]!

  """
  Identifier of the data format. The identifier is issued by the metabase. The
  format's meta data can be obtained by sending the GraphQL query
  `dataFormat(dataFormatId: ..., timestamp: ...) { ... }`
  to the metabase.

  The data format consists of a
  [media type](https://www.iana.org/assignments/media-types/media-types.xhtml)
  and additional information to unambiguously identify the specific format and
  to locate the format specification.
  """
  dataFormatId: Uuid!
}