Clarify Version: IDs and Timestamps

Some places (e.g. optical.json) have a combination of decentralized ID and timestamp to denote version.

In this case if you have an ID but no timestamp, does that mean that you are getting the latest version or all versions or is a timestamp always required?

Other places (e.g. component.json) have a centralOrDecentral ID for ID and then another centralOrDecentral ID for the version but no timestamp. Do some identifiers always mean a specific version and others do not?

Our understanding is the following:

central ID is created by the building envelope (ICON) database
decentral ID is ID issued by any other database
For example, In the IGSDB we have our own IDs which are the decentral IDs, and IGSDB will request the central ID from the ICON database

Regarding your understanding of central and decentral IDs: Yes, that's exactly what we mean.

You have to differentiate between the JSON Schemas that describe static data and the database GraphQL API specification that describes how to interact with databases. The former describe how results of GraphQL queries look in the form of JSON Schemas (and also standardize how, for example, optical data can be represented in the form of JSON documents). The GraphQL API specifies how you can interact with the database by sending GraphQL queries.

If I query the database with

query {
  allData(
    where: { componentId: { equalTo: "810e84b4-9ebf-416c-88ea-aade848f1fdf" } }
  ) {
    edges {
      node {
        id
        timestamp
        name
        description
      }
    }
  }
}

of all the latest data sets for the component with the given identifier, the data sets' id, timestamp, name, and description should be returned.

If I add an additional explicit argument timestamp

query {
  allData(
    where: { componentId: { equalTo: "810e84b4-9ebf-416c-88ea-aade848f1fdf" } },
    timestamp: "2009-06-15T13:45:30.381739Z"
  ) {
    edges {
      node {
        id
        timestamp
        name
        description
      }
    }
  }
}

only data sets that existed at the given timestamp and their data as it was at that time should be returned.

There should be no major changes to data sets. Versioning with timestamps is meant for patches like spelling corrections in descriptions. If there would be a major change, I would instead add another data set.

If we want or need timestamp at all is also open for debate. Maybe we together, LBNL and ISE, decide that minor changes need not be versioned and people should always get the latest versions? Also maybe because it's too much implementation trouble for little benefit?

building-envelope-data / api

Clarify Version: IDs and Timestamps #175