Home › The Technical Framework › Specifications and Instances

Specifications and Instances

You are viewing an archival website from the original trustmark pilot in 2013-2016. If you are looking for more recent content about the trustmark framework, please visit the Trustmark Initiative website.

This page discusses how we use normative technical specifications for TDs, trustmarks, and TIPs to enable participants in a trustmark marketplace to clearly define, understand, and compare each other’s trust and interoperability requirements.

The following topics are covered here.

Why Have Specs in a Trustmark Framework?

A normative specification, or spec, is a set of prescriptive statements that describe requirements to which an entity or artifact must conform. We define an instance as an artifact that conforms to a spec. Readers who are familiar with standards such as XML or JSON are likely to already understand the concepts of specs and instances. Now that we’ve covered what a spec is, it is important to understand what role specs play in a trustmark framework.

Several members of GTRI’s Pilot Team for this project have deep experience in the development of various data format specs, such as NIEM and N-DEx. In these cases and others, we have learned the value of normative specs as a required first step towards the development of a “software ecosystem”. In the case of the trustmark framework, this software takes the form of tools and libraries that can generate, process, and understand the structure of instances that conform to the various specs.

Relationships Between Specs and Instances

We have identified three specs that bring value to a trustmark framework; they are: a trustmark spec, a Trustmark Definition (TD) spec, and a Trust Interoperability Profile (TIP) spec. In addition, there are three types of instances in our trustmark framework: Trustmark Instances, TD Instances, and TIP Instances. Each type of instance must conform to its respective spec. Note that on this page and throughout this website, a “Trustmark Instance” is equivalent to a trustmark, a “TD Instance” is equivalent to a TD, and a “TIP Instance” is equivalent to a TIP.

The diagram below depicts the various relationships between the three specs and three types of instances.

Trustmark Framework ComponentsTrustmark Framework Components

As indicated in the diagram, the following relationships exist between the various components in the diagram.

  • The Trustmark Spec defines the basic structure of each Trustmark Instance, and each Trustmark Instance conforms to the Trustmark Spec.
  • The TD Spec defines the structure of each TD Instance, and each TD Instance conforms to the TD Spec.
  • The Trustmark Spec is used by the TD Spec.
  • Each TD Instance defines conformance criteria and assessment criteria for a specific type of Trustmark Instance.
  • The TIP Spec defines the structure of each TIP Instance, and each TIP Instance conforms to the TIP Spec.
  • TD Instances are used by TIP Instances.

The remaining sections of this page discuss each spec and instance type in greater detail.

The Trustmark Definition Spec

The TD Spec defines a common structure and syntax to which any TD must conform, regardless of the trust and interoperability requirements that it conveys. This common structure and syntax provides several benefits.

  • It ensures consistency and machine readability for all TDs.
  • It allows for greater ease of understanding a TD.
  • It makes TDs more likely to be considered for reuse, which leads to trustmark reuse.
  • It allows for standards-based TD software tools (e.g., TD authoring tools, trustmark assessment tools for TPs, etc.) to proliferate.

The TD Spec also ensures that all TDs contain the requisite minimal amount of information required to promote legitimacy and encourage reuse across multiple COIs. The following information is required for any TD.

  • Name of the Publishing TDO (Who wrote it?)
  • Canonical Location (URL) of the TD (Where is it available?)
  • TD Name (What is it called?
  • Description and Intended Purpose (What is it for?)
  • Target Stakeholder Audience (Who is it for?)
  • Date of Publication
  • Version Number

The following diagram depicts the TD Spec visually.

The Trustmark Definition SpecThe Trustmark Definition Spec

We have published formal requirements for TDs in the Trustmark Framework Technical Specification.

Trustmark Definition Instances

Each TD Instance, or TD, must conform to the TD Spec. A TD must contain the following information.

  • Conformance Criteria – A list of normative requirements to which the TR must conform in order to receive a trustmark under this TD
  • Assessment Process – A list of steps that the TP must follow in order to assess whether the TR conforms to the conformance criteria
  • TP Certification Criteria – A list of steps or other description of what an entity must do before it may become a TP for trustmarks issued under this TD
  • Metadata – A set of meta-level facts about this TD: who published it, what is its formal name, what is its formal location (URL), etc.

The diagram below visually depicts a sample TD Instance.

A Sample Trustmark Definition Instance

A Sample Trustmark Definition Instance

To see some actual TD instances, please visit this page.

The Trustmark Spec

The Trustmark Spec defines a common structure and syntax to which any trustmark must conform, regardless of the TD from which it was issued or the TP that issued it. This common structure and syntax provides several benefits.

  • It ensures consistency and machine understandability for all trustmarks.
  • It enables software tools (e.g., trustmark registries, trustmark format converters, etc.) to ingest and process trustmarks, thereby helping to automate some of the complexity that naturally arises within the trustmark marketplace.

The Trustmark Spec also ensures that every trustmark contains the minimal information required to verify its meaning and authenticity. The following information is required for any trustmark.

  • Name of the TP (Who issued it?)
  • Name of the TR (To whom was it issued?)
  • Pointer to the TD’s URL (What type of trustmark is it?)
  • Pointer to the Trustmark Policy (What are the terms and conditions for using it?)
  • Date of Issuance
  • Date of Expiration
  • Digital Signature of TP
  • Pointer to the Trustmark’s URL
  • Pointer to the Trustmark’s Revocation Indicator URL

The following diagram depicts the Trustmark Spec visually.

The Trustmark SpecThe Trustmark Spec

We have published formal requirements for trustmarks in the Trustmark Framework Technical Specification.

Trustmark Instances

Each Trustmark Instance, or trustmark, must conform to the Trustmark Spec. The diagram below visually depicts a sample Trustmark Instance. As per our spec, an actual Trustmark Instance is expressed in XML.

A Sample Trustmark InstanceA Sample Trustmark Instance

The Trust Interoperability Profile Spec

The TIP Spec defines a common structure and syntax to which any TIP must conform, regardless of the trust and interoperability requirements that it conveys. This common structure and syntax provides several benefits.

  • It ensures consistency and machine understandability for all trustmarks.
  • It enables software tools (e.g., trustmark registries, trustmark format converters, etc.) to ingest and process trustmarks, thereby helping to automate some of the complexity that naturally arises within the trustmark marketplace.

The TIP Spec also ensures that each TIP contains the required minimal amount of information required to promote legitimacy and encourage reuse where appropriate. The following information is required for any TIP.

  • Name of Publishing Entity (Who wrote it?)
  • Canonical Published Location
  • Description and Intended Purpose (Why was it written?)
  • Date of Publication
  • Version Number
  • Digital Signature of Publishing Entity (May be optional in some cases)

Note that the publishing entity of a TIP could be either a COI – which would publish a TIP as a form of policy guidance to its community members – or a TRP – which would publish a TIP as a formal statement of its trust and interoperability requirements.

The following diagram depicts the TIP Spec visually.

The Trust Interoperability Profile SpecThe Trust Interoperability Profile Spec

We have published formal requirements for TIPs in the Trustmark Framework Technical Specification.

Trust Interoperability Profile Instances

Each TIP Instance, or TIP, must conform to the TIP Spec. The diagram below visually depicts a notional sample TIP Instance. This particular sample TIP defines a list of trustmarks that IDPOs and SPOs must possess, respectively, to be trusted by other agencies (TRPs) within the U.S. LE community. Note that for each required trustmark, the TIP lists any applicable restrictions on the TPs that are considered trustworthy for the purpose of issuing that trustmark.

An actual TIP Instance must be expressed in XML.

A Sample Trust Interoperability Profile InstanceA Sample Trust Interoperability Profile Instance

To see some actual TIP instances, please visit this page.