Products Documentation

« Back to User Guide

What is a Product?

A Product is a collection of name/value pairs (properties), files (content), and references (links). Each product is uniquely identified by its product id. These key attributes are described as follows:

Product IDs

The source, type, and code uniquely identify a product and its associated content. The updateTimes indicate different versions of the same product, and products with more recent update times supersede products with less recent update times.

source

The product creator. Usually a network code.

type

The type of product. Multiple sources may create the same type of product.

code

A unique code, for a given source and type combination.

updateTime

When this version of content was created. Two products with the same source, type, and code, but different updateTimes are different versions of the same product. Previous versions of a product are superseded (though retained in the database) when newer versions arrive. versions

Status

A brief status code. Typically UPDATE or DELETE. Any value that is not DELETE is considered an update. Some product types define special status codes with specific meaning.

When a product producer deletes a product they send an update with a status DELETE, which is distributed like any other product. A product may be un-deleted by sending another update with status UPDATE.

Properties

Name/value pairs. Each property may only have one string value. These can be used to determine whether further processing is required. They are used to quickly identify high-level properties of the product without the need to parse its content data file(s).

Contents

Contents are optional, but are usually present when the status is not DELETE. Each content has a path, which corresponds to a filename.

Each content has the following attributes:

bytes

The inline byte content, typically a character string

Only applicable to inline content

length

Length (size) of the content file in bytes

modified (lastModified)

The ISO 8601 timestamp of when the content file was last modified

path

The path, relative within the product, where this file is located

sha256

The SHA 256 hash of the content file

type (contentType)

The content type of the file

url

The absolute URL from where this file may be downloaded

This may be a data URL or a web-accessible URL. This is not applicable to inline content.

Non file (inline) content

Each product may have one piece of content that is a stream of bytes. It has an empty path ""and is not stored in a file. Typically this content is read from standard input, and also delivered to consumers via standard input. Inline content URL

Links

A product may include links to other products and resources. Links have a relation, which specifies how the resource is related to the product and a uri which specifies the destination of the link. There may be multiple links for each type of relation.

Signature

Producers generate a signature which may be verified by both hubs and consumers. The signature consists of a hash of a digest of the product. The hash is generated using a private key and verified using a public key.

Production hubs require a signature, and a keypair must be registered before products are sent.

Signature Version

Different signature versions use different digest and hashing algorithms to be computed.

Example JSON Representation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
"product": {
  "id": {
    "code": "product_code",
    "source": "product_source",
    "type": "product_type",
    "updateTime": "YYYY-MM-DDTHH:ii:ssZ"
  },
  "links": [
    {
      "relation": "Description of relation",
      "uri": "urn:usgs-product:..."
    }
  ],
  "properties": {
    "property_name_one": "propety_value_one",
    "property_name_two": "property_value_two"
  },
  "signature": "Base64 encoding of computed signature",
  "signatureVersion": "v2",
  "status": "product_status",
  "contents": {
    "file.ext": {
      "length": 12345,
      "modified": "YYYY-MM-DDTHH:ii:ssZ",
      "sha256": "Base64 encoding of file content SHA 256",
      "type": "Content-Type of file content",
      "url": "https://.../file.ext"
    }
  }
}

Designing a New Product Type

The information contained in this section represent best practice when generating new products.

Product Properties

Properties should be defined for important attributes of your product. They allow recipients to quickly determine whether they should process a product, without extensive parsing.

If the product is associated to a specific seismic event, it should include standard properties to assist in event association.

Products may also have properties that are specific to that product type.

Contents.xml File

It is recommended you include with your product a “contents.xml” file. This file describes all of the contents you are sending with your product. It helps the web page to better display your product and ultimately determines what content users will be able to easily download from the web site.

The contents.xml file format is defined with a contents.xsd file. You must understand how to read XML schema (XSD) files to properly generate a contents.xml file.

Grouping Content

All the information in a product is updated at once when a new product arrives. It is not possible to update one aspect of a product while leaving the other aspects unchanged. For example, one cannot update a single content file in a product or modify a single product property without sending a complete new version of the product.

For this reason, when deciding which information is to be included with a new product type, consider when this information is updated as well as its topical relation.

Product Code Conventions

A product code must be unique forever, from the same source and type. Product creators also reuse the code to update or delete the product.

For event-related products, an eventid makes a good code because it also must be unique forever. Examples include: us2011abcd and nc12345678.

For non-event-related products another ID scheme is required. Timestamps are often useful in this situation when the products are related to a time window.

An internal database key can be used.

Last modified: Wed Jul 31 21:55:59 UTC 2024