atproto_openapi/refs

Lexicon ref -> OpenAPI component-key resolution. Every PropRef/ ItemRef/BodySchemaRef/union member string in the AST is one of three spellings (#localName, nsid#name, bare nsid); this module reduces all three to the canonical Ref(nsid, name) pair (bare nsid canonicalizes to Ref(nsid, "main")) and derives the components/ schemas key from it. OpenAPI component keys must match ^[a-zA-Z0-9._-]+$, so the lexicon’s # separator cannot appear in one; _ is used instead, which is safe because NSID segments and def names never contain _. Two distinct canonical refs landing on the same key is a collision, reported via find_collisions rather than silently merged, mirroring how atproto_sdl/atproto_mlf report NSID collisions. See docs/lexicon-openapi.md for the full scheme.

Types

Ref

A ref reduced to its canonical (nsid, name) form. name is always present: a bare nsid ref canonicalizes to name: "main".

pub type Ref {
  Ref(nsid: String, name: String)
}

Constructors

```
Ref(nsid: String, name: String)
```

RefError

pub type RefError {
  EmptyRef
  MultipleFragments(raw: String)
  EmptyLocalName(raw: String)
  KeyCollision(key: String, first: Ref, second: Ref)
}

Constructors

```
EmptyRef
```
The raw ref string was empty.
```
MultipleFragments(raw: String)
```
The raw ref string had more than one #.
```
EmptyLocalName(raw: String)
```
The raw ref string had a # with nothing after it.
```
KeyCollision(key: String, first: Ref, second: Ref)
```
Two distinct canonical refs derive the same component key.

Values

canonicalize

pub fn canonicalize(
  raw: String,
  doc_id: String,
) -> Result(Ref, RefError)

Resolve a raw ref string against the NSID of the doc it appears in. #foo resolves to Ref(doc_id, "foo"); nsid#foo to Ref(nsid, "foo"); bare nsid to Ref(nsid, "main").

component_key

pub fn component_key(ref: Ref) -> String

The components/schemas key for a canonical ref: nsid when name is "main", else nsid <> "_" <> name.

describe

pub fn describe(error: RefError) -> String

find_collisions

pub fn find_collisions(refs: List(Ref)) -> List(RefError)

Report every case where two distinct canonical refs land on the same component key, rather than letting the second silently overwrite the first in the emitted components/schemas map. Empty when refs has no collisions.

schema_pointer

pub fn schema_pointer(
  raw: String,
  doc_id: String,
) -> Result(String, RefError)

The $ref JSON pointer for a raw ref string, resolved against the containing doc’s id: #/components/schemas/<component_key>.