Is there a way to define a "custom" [[spec: xxx]] -- to an external spec other than the pre-defined ones?

[swcurran]

I love that I can reference W3C and IETF specs using the [[spec:rfc123]] syntax, get a mouse over link and an appendix list of specs.

Is there a way that I can use a spec reference to a any URL I want -- specs that Spec-Up doesn't know about? For example, I want to reference the DIF "Linked Verifiable Presentation" spec. If I do [[spec:linked-vp]], I just see that literal in the rendered text. Is there a way to add my own URLs that I defined as "specs" so that they benefit from the spec: feature? Other examples -- ISO specs (although that might have to be to Wikipedia to avoid the paywall), W3C working documents, etc.

Thanks!

[swcurran]

RTFM -- see documentation section on External Specs. Solved.

[swcurran]

And trying it out makes me realize that External Specs are not the same, even though the have such a promising name.

Is there a way to extend the known [[spec:xyz]] references?

[csuwildcat]

I'm sure I could figure something out. Why don't we take a look at IIW next week?

[csuwildcat]

Is your main goal to enable one-offs to have the same format that the other refs have, or to create and draw from a new corpus of formatted refs? The former would be easier, but we could do the latter if we had a location to host the new ref catalog.

[swcurran]

My main goal was to be able to add the needed specs to the JSON file, and then reference them in the various categories in the document — so the first one from your list. I didn’t realize until talking to @brianorwhatever that there was a standard list of reference-able specs. That feature is great, and it would be nice to have a link to that list. But ultimately, any list cannot include everything needed for a given spec, so I think having a way to add spec-specific references is necessary.

[henkvancann]

[[spec]] is another tool and another concept than [[xref:]] and [[tref:]], they can both be used in the future.

[[spec]] refers to whole documents/specifications and offers a categorisation.

[[xref:]] and [[tref:]] are references to individual external definitions in related spec-up-(t)-based repos/specification

[[xref:]] is already present in DIF's Spec-Up, [[tref:]] will be added shortly.

@swcurran : Is there a way to define a "custom" [[spec: xxx]] -- to an external spec other than the pre-defined ones.

You could always use bare URLs, but then you miss the sophisticated characteristics of xref and tref, which are popups at hoovering, traceability, local backup, and diffs with git. That's because we need to define them in Specs.json.

[swcurran]

@brianorwhatever has implemented the feature that I was looking for. AFAIK, it is not in the DIF version of SpecUp. I’m using it in did:wehvh — notable, In the specs.json file, we can add specs as defined below, and then reference them in a spec as [[spec:multiformats]] (for example), get the mouseover popup, the link and an entry in the list of specs produced by inserting [[spec]] into the markdown. Works great.

@brianorwhatever also shared with me that the default lists of specs are the W3C, IETF and WhatWG lists from the tobie/specref repo. See line 20 in this SpecUp file

      "external_specs": [
        {
          "multiformats": {
            "href": "https://datatracker.ietf.org/doc/draft-multiformats-multibase/08/",
            "title": "Multiformats",
            "rawDate": "2024-02-21",
            "authors": [
              "Juan Benet",
              "Manu Sporny"
            ],
            "status": "Internet Draft"
          }
        },
        {
          "di-eddsa-v1.0": {
            "href": "https://www.w3.org/TR/vc-di-eddsa",
            "title": "Data Integrity EdDSA Cryptosuites v1.0",
            "rawDate": "2024-12-08",
            "authors": [
              "Dave Longley",
              "Manu Sporny"
            ],
            "status": "W3C Technical Recommendation"
          }
        }
      ]

[henkvancann]

@swcurran In spec-up of DIF we find quite a few references to [[Spec......]]; see here: https://github.com/decentralized-identity/spec-up/blob/master/single-file-test/spec.md. And it's also generated in the example: https://identity.foundation/spec-up/#normative-references
so these tags

[[spec:.....]]
[[spec-norm]]
[[spec-inform]]

are handled by DIF's spec-up already, we've yet to find out where and how :)

[swcurran]

If you are asking how they work, you put those references [[spec:rfc3339]], and it provides a popup summary of the reference, and a link to the footnote. The target of those links are generated when you put [[spec]] on a Markdown page as a properly formatted footnote list of all spec references in the Spec.

The tricky part is how do you know what the list of valid “specs” are? You can’t use just anything. That is where my comment above comes in — the default lists of specs are the “W3C", “IETF" and “WhatWG" lists from the tobie/specref repository of specification references. See line 20 in this SpecUp file. I downloaded the JSON files locally, so I can search them to find the names of specs.

What @brianorwhatever implemented was the ability to put additional external specs into the SpecUp JSON file, so that I can add my own set of “spec” references that I can refer to in the document, and have listed in the footnote list of specs.

Does that make sense?

[henkvancann]

Yes, very much, thank you! We've yet to put everything in the right relationship between them: spec, def, ref, xref, and tref.

A first try:

External references in Spec-Up

We distinguish external references to Specification sections of all kinds and (external) references to individual term-definitions in Spec-Up(-T)-based Specifications.

'* All kinds using Tobie's specref engine.

flowchart LR

    K(Tobie's Spec references)
    K -.->|"github.com/tobie/specref/.../w3c.json"|V
    K -.->|"github.com/tobie/specref/.../ietf.json"|W
    K -.->|"github.com/tobie/specref/.../whatwg.json"|X

 subgraph one ["API-based PER SECTION! (refs.json)"]
    V
    W[IETF]
    X[WhatWG]
    L[Local spec references]
    end
    
 subgraph two [Spec-Up-T based PER TERM!]
    A(Specification) 
    B[specs.json]
    A -.->|"[[tref:]] and [[xref:]]"| G
    G[ToIP Main Glossary] <-.-> |"[[tref:]] and [[xref:]]"|U
    A -.->|def + ref|A
    G -.->|def + ref|G
    U[KERI Main Glossary] -.->|def + ref|U
    end
    B -.-> |Brian Richter's add on|L
    A <--> |"[[spec:]]"|V[Standard W3C]
    A -.->|maintenance| V
    A <-.->|"[[tref:]] and [[xref:]]"| U

Loading

In DIF Spec-Up github.io page, I studied this description: https://identity.foundation/spec-up/#external-spec-references. Because Spec-Up-T is initially a Spec-Up fork, it should have the same capabilities. However, as you mentioned, Brian's fixes and the add-on are not in one of them, yet.

The main difference I see is that Spec-Up-T has references to individual term defs (ref, xref, tref) kept version-managed with git. Whereas any section defined with [[spec{[-]foo}:,id={any id}]] and delimited with [[/spec{[-]foo}]] is the content of the reference that you refer to with [[spec{[-]foo}:{any-id}]] and present with either [[spec]] or any other extra tag [[spec{[-]foo}]] for a divided lists to categorize/print later. There is no version control on the [[spec:]] mechanism; you have to maintain the reference yourself, I think.

[ ] = mandatory, { } = optional

The two mechanisms def-ref-xref-tref and spec can be used together and serve a different purpose.

Example declaration in the source:

[[spec-inform:id=INFO-annexA]]
{anything}
[[/spec-inform]]

Example reference in the destination

[[spec-inform:INFO-annexA]]

which shows as: [INFO-annexA]

Example print in the destination

## General references:
[[spec]]
### Informative references:
[[spec-inform]]

Still not sure whether I fully grasp the working, feel free to put me in the right direction.

@brianorwhatever, could you offer your amendments as a PR to https://github.com/trustoverip/spec-up-t? Or tell us how to integrate it?

Thanks!

[henkvancann]

This is the report of a discussion in the KERI team about the wanted features of the [[spec]] tag:
A. In your own spec-up(-t) document you should be able to declare a part of the document as normative or informative and give it a unique id. Multiple sections of both types should be possible in one document.
B. Both references to local (in the dec itself) and external specification documents should be possible.
C. the links to local and external spec references should be styled differently.