§ Spec-Up Example

Specification Status: Draft

Latest Draft: https://identity.foundation/spec-up

Editors:
Daniel Buchner
Participate:
GitHub repo
File a bug
Commit history

§ Abstract

Let’s face it, other tools and generators for writing technical specifications aimed at standards bodies or industry groups are cumbersome, underwhelming, and lack the features you might want in a technical specification document. Spec-Up’s goal is to deliver you a better spec-writing experience with far less effort and tedium than other tools in the ecosystem. Spec-Up is a simple tool that auto-generates great specs from markdown. The version of markdown Spec-up uses contains all the same features you might expect from common implementations, like GitHub, but adds much more, including notice blocks, complex tables, charts, advanced syntax highlighting, UML diagrams, etc.

§ Getting Started

Using Spec-Up is easy peasy lemon squeezy:

  1. npm install spec-up

  2. Create a specs.json file in the root folder of your repository to specify configuration values used in the generation of your spec documents. The values in your specs.json file include things like where your spec’s markdown files are located, where to output the generated spec document, and various metadata values used in rendering, such as the title, logo, and repo links for each of your specs. The following are the required/optional fields supported in the specs.json config file:

    • spec_directory (STRING, required) - You must specify the repo-root-relative location of your spec’s markdown file directory. You MUST name your spec’s markdown file spec.md and locate it in your spec_directory for the tool to automatically find and use it for rendering. If you want to use a different name for the markdown file, or you have multiple markdown files you would like the tool to assemble into one document, you must specify them using the optionalmarkdown_paths field described below. See the “multi-file” example in the spec-up repo.
    • title (STRING, required) - You must add a title for your spec, which will be rendered in the generated document’s H1 text and page title.
    • markdown_paths (ARRAY, optional) - If you want to name your spec’s markdown file something other than spec.md, or you have multiple files you would like assembled into a single output document, you must specify their paths as array entries in the order you would like them assembled. The paths in this array are assumed to be based on the spec_directory you specified, so DO NOT repeat the full root relative path.
    • katex (BOOLEAN, optional) - To enable TeX support via KaTeX, set this property to true. After rendering, be sure to copy the fonts/ subdirectory, containing the necessary web fonts.
    • output_path (STRING, optional) - If you want the generated spec document to be output to a different location than the spec_directory you specified (e.g. the project root for GitHub Pages publishing) you can specify another root relative path (use ./ for root), and the tool will write the document file there instead.

  3. In your main node.js file, drop in this bad boy: require('spec-up')()

Boom! That’s it. Spec-Up will auto-detect modifications to files in your spec_directory and auto-generate your spec’s updated HTML document every time you save a change.

Usage

If your spec.json and package.json and package-lock.json files are in working order and in the root folder of the repo from which it will be deployed, Spec-up can be called by command line (from the root of your repo) in three different modes:

command behavior
npm run edit after rendering, this will stay running and the gulp library will watch the source files in your spec directory/ies for changes and re-render any time you save a file. Opening these rendered files in a browser and refreshing them will keep you up to date.
npm run render this renders the site once and does not keep a gulpy watch on the underlying files.
npm run dev this enables debugging features.

§ Table of Contents

<-- You see that beautiful TOC over there to your left? (tap the header link to slide it out on mobile) Yeah, you don’t need to do a damn thing, that just magically appears based on your use of h2, h3, and h4 headings.

§ Term References

§ Definition Lists

Many specs may want to include a section for terminology references, and Definition Lists are a great way to do that. Here’s how to leverage Spec-Up’s automatic term reference features via Definition List markup:

[[def: Term 1, Term One]]:
~ This is the first term we will define.

[[def: Term 2, Term Two]]:
~ This is the second term, but not the last.

[[def: Term 3, Term Three]]:
~ This is the last term, because you know what they say: third term's the charm!
Term 1:
This is the first term we will define.
Term 2:
This is the second term, but not the last.
Term 3:
This is the last term, because you know what they say: third term’s the charm!

Now let’s refer to some of the terms defined above to show how the auto-linking of terms works: Term 1, Term Two, Term 3. Additionally, as long as you define your terms using Definition Lists (as seen in the markdown above), you will be able to hover any reference to a term to see a tooltip with its definition.

§ Table-defined Terms

You can also reference table-oriented terms and definitions which are decomposed into heading-titled attributes in distinct cells:

Variable           | Default Value | Max Value
------------------- | -------------- | ---------
[[def: Variable 1]] | 123          | 9999
Variable Default Value Max Value
Variable 1 123 9999

Anytime you add a definition of a term in the first column of a table, like Variable 1, it will link to the cell and display a tooltip with the entire set of row values when you hover the term.

§ External Term References

It is possible to include references to terms from external spec-up generated specifications. To include a source you would like to pull references from include an external_specs array in your spec config. The value should be a key/value object where the key is used in the external reference below and the value is the URL of the external spec.

EXAMPLE
{
  "specs": [
    {
      ...
      "external_specs": [
        {"PE": "https://identity.foundation/presentation-exchange"}
      ]
    }
  ]
}

To include an external term reference within your spec use the following format [[xref: {title}, {term}]] where {title} is the title given to the spec in the config and {term} is the term being used. For example using the PE spec given in the example above Holder

§ Blockquote

To be, or not to be, that is the question: Whether 'tis nobler in the mind to suffer The slings and arrows of outrageous fortune, Or to take arms against a sea of troubles And by opposing end them. To die—to sleep, No more;

§ Notices

::: note Basic Note
  Check this out.
:::
NOTE

Check this out.

NOTE

Here’s another.

NOTE

And one more!

NOTE

One last note!!!

::: issue Issue Notice
  I take issue with that, kind sir.
:::
ISSUE

I take issue with that, kind sir.

::: warning Warning Notice
  Houston, I think we have a problem
:::
WARNING

Houston, I think we have a problem

::: todo Really Important
  Get this done!
:::
TODO

Get this done!

::: example Code Example
  Put your code block here
:::
EXAMPLE
// Some comment in JSON
{
  "foo": "bar",
  "baz": 2
}

§ Content Insertion

Use the following format to pull in content from other files in your project:

This text has been inserted here from another file: [[insert: ./single-file-test/assets/test.text]]

This text has been inserted here from another file: Beam me in, Scotty!

You can even insert content within more complex blocks, like the JSON object below which is being pulled in and rendered in a syntax-highlighted example block:

::: example Code Example
```json
[[insert: ./single-file-test/assets/test.json]]
```
:::
EXAMPLE
{
  "foo": {
    "bar": 1
  }
}

§ Tables

Stage | Direct Products | ATP Yields
----: | --------------: | ---------:
Glycolysis | 2 ATP ||
^^ | 2 NADH | 3--5 ATP |
Pyruvaye oxidation | 2 NADH | 5 ATP |
Citric acid cycle | 2 ATP ||
^^ | 6 NADH | 15 ATP |
^^ | 2 FADH2 | 3 ATP |
**30--32** ATP |||
[Net ATP yields per hexose]
Net ATP yields per hexose
Stage Direct Products ATP Yields
Glycolysis 2 ATP
2 NADH 3–5 ATP
Pyruvaye oxidation 2 NADH 5 ATP
Citric acid cycle 2 ATP
6 NADH 15 ATP
2 FADH2 3 ATP
30–32 ATP 
|--|--|--|--|--|--|--|--|
|♜|  |♝|♛|♚|♝|♞|♜|
|  |♟|♟|♟|  |♟|♟|♟|
|♟|  |♞|  |  |  |  | |
|  |♗|  |  |♟|  |  | |
|  |  |  |  |♙|  |  | |
|  |  |  |  |  |♘|  | |
|♙|♙|♙|♙|  |♙|♙|♙|
|♖|♘|♗|♕|♔|  |  |♖|
♜ ♝ ♛ ♚ ♝ ♞ ♜
♟ ♟ ♟ ♟ ♟ ♟
♟ ♞
♗ ♟
♙
♘
♙ ♙ ♙ ♙ ♙ ♙ ♙
♖ ♘ ♗ ♕ ♔ ♖

§ Sequence Diagrams

```mermaid
sequenceDiagram
  Alice ->> Bob: Hello Bob, how are you?
  Bob-->>John: How about you John?
  Bob--x Alice: I am good thanks!
  Bob-x John: I am good thanks!
  Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row.

  Bob-->Alice: Checking with John...
  Alice->John: Yes... John, how are you?
```
sequenceDiagram Alice ->> Bob: Hello Bob, how are you? Bob-->>John: How about you John? Bob--x Alice: I am good thanks! Bob-x John: I am good thanks! Note right of John: Bob thinks a long
long time, so long
that the text does
not fit on a row. Bob-->Alice: Checking with John... Alice->John: Yes... John, how are you?

§ Flows

```mermaid
graph TD
  A[Start] --> B{Is it?}
  B -->|Yes| C[OK]
  C --> D[Rethink]
  D --> B
  B -->|No| E[End]
```
graph TD A[Start] --> B{Is it?} B -->|Yes| C[OK] C --> D[Rethink] D --> B B -->|No| E[End]

§ Charts

```chart
{
  "type": "pie",
  "data": {
    "labels": [
      "Red",
      "Blue",
      "Yellow"
    ],
    "datasets": [
      {
        "data": [
          300,
          50,
          100
        ],
        "backgroundColor": [
          "#FF6384",
          "#36A2EB",
          "#FFCE56"
        ],
        "hoverBackgroundColor": [
          "#FF6384",
          "#36A2EB",
          "#FFCE56"
        ]
      }
    ]
  }
}
```
{"type":"pie","data":{"labels":["Red","Blue","Yellow"],"datasets":[{"data":[300,50,100],"backgroundColor":["#FF6384","#36A2EB","#FFCE56"],"hoverBackgroundColor":["#FF6384","#36A2EB","#FFCE56"]}]}}

§ Syntax Highlighting

```json
{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [{
    "id":"did:example:123456789abcdefghi#vcs",
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}
```

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:example:123456789abcdefghi",
  "authentication": [{ 
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationKey2018",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  "service": [{
    "id":"did:example:123456789abcdefghi#vcs",
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}

§ TeX Math Equations

When the katex option is enabled, the KaTeX math engine is used for TeX rendering. You can find a list of supported features and examples here: https://katex.org/docs/supported.html.

(x2y2)=(ABCD)⋅(x1y1)\begin{pmatrix}x_2 \\ y_2 \end{pmatrix} = \begin{pmatrix} A & B \\ C & D \end{pmatrix}\cdot \begin{pmatrix} x_1 \\ y_1 \end{pmatrix}

abcdefghi\def\arraystretch{1.5} \begin{array}{c:c:c} a & b & c \\ \hline d & e & f \\ \hdashline g & h & i \end{array}

a+b+c⏟Note: such math, much wow.\underbrace{a+b+c}_{\text{Note: such math, much wow.}}

§ Tab Panels

{
  "foo": "foo",
  "baz": 1
}

{
  "foo": "bar",
  "baz": 2
}

Spec-Up automatically upgrades the links of certain sites, like GitHub. GitHub is the only supported site with Fancy Links right now, but we’ll be adding more as we go.

§ GitHub

§ External Spec References

You can reference external specifications from IETF, W3C, and WHATWG as follows:

  1. Anywhere in your document you want to referece an external specification, use the spec-prefixed custom token format: [[spec:RFC4122]]
  2. Wherever in your document you want to print out all your external specification references, use the spec custom token format without any spec name: [[spec]]

Here are a set of example references that are distributed among the reference groups spec, spec-norm, spec-inform:

§ Default References

This is what is printed out when you include the [[spec]] custom token in your Markdown:

RFC3548
The Base16, Base32, and Base64 Data Encodings. S. Josefsson, Ed.; 2003-07. Status: Informational.
RFC7518
JSON Web Algorithms (JWA). M. Jones; 2015-05. Status: Proposed Standard.

§ Normative References

This is what is printed out when you include the [[spec-norm]] custom token in your Markdown:

DID-CORE
Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed; 2022-07-19. Status: REC.
DID-SPEC-REGISTRIES
DID Specification Registries. Orie Steele; Manu Sporny; 2023-09-11. Status: NOTE.

§ Informative References

This is what is printed out when you include the [[spec-inform]] custom token in your Markdown:

RFC6901
JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.; 2013-04. Status: Proposed Standard.
RFC7230
Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. R. Fielding, Ed.; J. Reschke, Ed.; 2014-06. Status: Proposed Standard.

✕
Table of Contents ✕
Claim
An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
Claim
An assertion made about a Subject. Used as an umbrella term for Credential, Assertion, Attestation, etc.
Conformant Consumer
An entity that follows the specified processing rules to consume a Presentation Definition or Presentation Submission that conforms to this specification.
Conformant Consumer
An entity that follows the specified processing rules to consume a Presentation Definition or Presentation Submission that conforms to this specification.
Conformant Producer
An entity that produces a Presentation Definition or Presentation Submission that conforms to this specification.
Embed Locations
Embed Locations are the specific paths and indexes per Embed Target where the Verifier can expect to find the Presentation. See Embed Locations.
Embed Target
Embed Targets are data formats used in messaging protocols that may be used to transport a Presentation Submission. See Embed Targets.
Embed Target
Embed Targets are data formats used in messaging protocols that may be used to transport a Presentation Submission. See Embed Targets.
Feature
Features enable Verifiers to express, and Holders to support, extended functionality (relative to the base objects) by defining one or more properties on one or more objects.
Feature
Features enable Verifiers to express, and Holders to support, extended functionality (relative to the base objects) by defining one or more properties on one or more objects.
Holder
Holders are entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. A Holder is a Conformant Consumer of a Presentation Definition and a Conformant Producer of a Presentation Submission.
Holder
Holders are entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. A Holder is a Conformant Consumer of a Presentation Definition and a Conformant Producer of a Presentation Submission.
Holder Binding
Holder Bindings are requirements of a certain type of relationship between the Holder and the Claims within the Presentation. See Holder Binding.
Decentralized Web Node
Some examples refer to an unfamiliar query protocol, dwn://, as a way of storing and querying schemata and other resources. While orthogonal to this specification and not yet on a standards track, the concept of “decentralized web nodes” proposes an architecture that may be of interest or utility to implementers of this specification. For more information, see the draft specification hosted at the decentralized identity foundation here
Decentralized Web Node
Some examples refer to an unfamiliar query protocol, dwn://, as a way of storing and querying schemata and other resources. While orthogonal to this specification and not yet on a standards track, the concept of “decentralized web nodes” proposes an architecture that may be of interest or utility to implementers of this specification. For more information, see the draft specification hosted at the decentralized identity foundation here
Input Descriptor
Input Descriptors are used by a Verifier to describe the information required of a Holder before an interaction can proceed. See Input Descriptor.
Input Descriptor
Input Descriptors are used by a Verifier to describe the information required of a Holder before an interaction can proceed. See Input Descriptor.
Input Descriptor Object
Input Descriptors Objects are populated with properties describing what type of input data/Claim, or sub-fields thereof, are required for submission to the Verifier. See Input Descriptor Object.
Input Descriptor Object
Input Descriptors Objects are populated with properties describing what type of input data/Claim, or sub-fields thereof, are required for submission to the Verifier. See Input Descriptor Object.
Link Secrets
Link Secrets are values held by the Holder but hidden from other parties. They are typically incorporated into cryptographic signatures used in claims to demonstrate correlation while preventing replay attacks. An Issuer may ascertain that a Holder possesses a link secret without its disclosure. See Link Secrets.
Presentation Definition
Presentation Definitions are objects that articulate what proofs a Verifier requires. These help the Verifier to decide how or whether to interact with a Holder. Presentation Definitions are composed of inputs, which describe the forms and details of the proofs they require, and optional sets of selection rules, to allow Holders flexibility in cases where many different types of proofs may satisfy an input requirement. See Presentation Definition.
Presentation Request
Presentation Requests are transport mechanisms for Presentation. Presentation Requests can take multiple shapes, using a variety of protocols and signature schemes not refined in this specification. They are sent by a Verifier to a Holder. Defining Presentation Requests is outside the scope of this specification. See Presentation Request.
Presentation Submission
Presentation Submissions are objects embedded within target claim negotiation formats that unify the presentation of proofs to a Verifier in accordance with the requirements a Verifier specified in a Presentation Definition. See Presentation Submission.
Subject
Subjects are the entities about which Claims are made. The Subject may not be the same entity as the Holder
Subject
Subjects are the entities about which Claims are made. The Subject may not be the same entity as the Holder
Submission Requirement
Submission Requirements are objects that define what combinations of inputs must be submitted to comply with the requirements a Verifier has for proceeding in a flow (e.g. credential issuance, allowing entry, accepting an application). See Submission Requirements.
Submission Requirement
Submission Requirements are objects that define what combinations of inputs must be submitted to comply with the requirements a Verifier has for proceeding in a flow (e.g. credential issuance, allowing entry, accepting an application). See Submission Requirements.
Submission Requirement Object
Submission Requirement Objects describe valid combinations of inputs in a Presentation Submission. See Submission Requirement Objects.
Submission Requirement Object
Submission Requirement Objects describe valid combinations of inputs in a Presentation Submission. See Submission Requirement Objects.
Submission Requirement Rule
Submission Requirement Rules describe combinatorial rules within a Submission Requirement Object when processing inputs. They may be nested. See Submission Requirement Rules.
Submission Requirement Rule
Submission Requirement Rules describe combinatorial rules within a Submission Requirement Object when processing inputs. They may be nested. See Submission Requirement Rules.
Verifier
Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. A Verifier is a Conformant Producer of a Presentation Definition and a Conformant Consumer of a Presentation Submission.
Verifier
Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. A Verifier is a Conformant Producer of a Presentation Definition and a Conformant Consumer of a Presentation Submission.
OIDC
Open ID Connect. Jones, M., Bradley, J., and N. Sakimura. Status: Approved Specification
Linked Data Proof
Data Integrity 1.0. Dave Longley, Manu Sporny. 2022-03. Status: Draft Community Group Report.
Linked Data Proof
Data Integrity 1.0. Dave Longley, Manu Sporny. 2022-03. Status: Draft Community Group Report.
CHAPI
W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
CHAPI
W3C Credential Handler API 1.0. Dave Longley, Manu Sporny. 2020-2-19. Status: Draft Community Group Report.
DIDComm
DIF DIDComm Messaging. Daniel Hardman, Sam Curren. Status: Working Group Draft.