🥮 mooncakes.io
    Sign in

    moonuritemplate

    Offline API contract workspaces, dependency-aware updates and consumer upgrade gates; RFC 6570 compatibility

    api-contract
    openapi
    schema
    incremental
    rfc6570
    Download zip
    Author
    Version
    0.3.0
    License
    Apache-2.0
    Repository
    Last updated
    7 hours ago
    Downloads
    18

    Dependencies

    #MoonUriTemplate — offline API contract workspaces

    Version 0.3.0 adds JSJ222/moonuritemplate/contracts: a bounded OpenAPI 3.1 JSON importer, typed request/response validation, offline cross-document schema locks, transitive reverse dependencies, immutable atomic document updates, conservative change review and consumer-driven upgrade gates. Schema interpretation reuses moonbitstack/moonschema@0.2.0 (Apache-2.0); workspace ownership, dependency tracking and governance are original project code.

    The goal is contract lifecycle management rather than another RFC 6570 expander. The root URI package remains source compatible. Existing MoonBit contract validators and compatibility tools are acknowledged in the support matrix and ecosystem comparison.

    import { "JSJ222/moonuritemplate/contracts" @contracts, }

    Run three asserted scenarios: moon run examples/contract_sdk --target wasm-gc, moon run examples/contract_workspace --target wasm-gc, and moon run examples/contract_ci --target wasm-gc. They cover SDK boundaries, shared DTO evolution and CI release gates. The examples perform no HTTP requests.

    Only the documented profile is supported: typed decoded values, exact JSON media types and an explicit offline schema lock. Unsupported features fail explicitly. No YAML, automatic fetching, authentication execution, raw HTTP decoding, recursive/dynamic references, $id scope rebasing or complete OpenAPI validation. Schema changes require explicit review; passing examples is not a universal compatibility proof. Calls sharing a workspace must be serialized because the upstream interpreter is not concurrently reentrant.

    python tools/compare_contract_oracle.py compares 351 original fixtures with python-jsonschema 4.26.0 (Draft 2020-12). moon run benchmarks/contract_management --target native --release asserts cold/incremental equivalence and prints actual rebuild/replay counts and timing percentiles. See API contracts for reproducibility and limitations.

    #Legacy URI package

    Current source adds runtime parameter contracts (Template::with_contract) and immutable incremental links (TemplateCatalog::start_session, LinkSession::update). See runtime integrations and the contracts / incremental_links examples. On affected Windows 0.10.16, use ./tools/windows/moon.ps1; see toolchain notes.

    Pure MoonBit RFC 6570 Level 4 URI Template parser and expander for wasm, wasm-gc, JavaScript, and native targets.

    Compile a template once, then expand it with typed scalar, list, or ordered associative values. The library supports all eight defined operators, prefix and explode modifiers, UTF-8 percent encoding, sparse composites, bounded processing, source-aware analysis, binding preflight, and a conservative JSON bridge.

    Reusable catalogs, partial bindings, batch rendering, source-to-output spans, variable profiles, and opt-in template policies support SDK generators and hypermedia services. Every API returns typed errors; network destination validation remains the caller's responsibility.

    Template::measure computes the exact expanded length without assembling the URI, and the positive conformance fixtures check that measurement agrees with rendering. Template::diff_contract reports selected static changes for API reviews; it does not prove URI equivalence.

    Run from a source checkout:

    moon check --target all --deny-warn
moon build --target all --deny-warn
moon test --target all --deny-warn
moon run examples/api --target wasm-gc

    moon run examples/mcp --target wasm-gc and moon run examples/hypermedia --target wasm-gc demonstrate two further uses. The main README documents the API, security boundaries, and conformance scope.

    The runtime implementation is original. Apache-2.0 test fixtures from uri-templates/uritemplate-test are pinned and attributed in THIRD_PARTY.md. The project itself is Apache-2.0 licensed.

    #十月第二轮：目录迁移与请求审查

    TemplateCatalog::diff_catalog(next) 列出新增、删除和变更端点，连字面量路径变化也保留；每项变更附原有变量/运算符契约报告。inspect_requests 检查混合请求的全部诊断，限制请求、绑定及结果数量，返回请求索引和变量名，不包含绑定值。缺失变量属于提示，普通 RFC 展开允许省略。

    expand_requests 现在先调用精确计量，再构造输出，确保总预算超限在生成 URI 数组前被拒绝。计量仍有输入编码的临时分配，展开需额外遍历一次。运行 moon run examples/maintenance --target wasm-gc。详见 功能与边界。

    BatchError

    source
    pub(all) enum BatchError {
      TooManyInputs
      TotalOutputTooLong
      InvalidItem(Int, ExpandError)
    }

    A bounded batch expansion failed before returning a partial result.

    BatchError::code

    source
    fn BatchError::code(self : BatchError) -> String

    BatchError::index

    source
    fn BatchError::index(self : BatchError) -> Int?

    Return the zero-based row number for a per-row expansion failure.

    BindingChange

    source
    pub(all) enum BindingChange {
      SetBinding(String, Value)
      RemoveBinding(String)
    }

    BindingIssue

    source
    pub(all) enum BindingIssue {
      Missing(String)
      Unused(String)
      Duplicate(String)
      CompositePrefix(String)
    }

    A preflight observation about the supplied bindings. Missing variables are informational: RFC 6570 deliberately permits undefined variables.

    BindingIssue::code

    source
    fn BindingIssue::code(self : BindingIssue) -> String

    BindingIssue::name

    source
    fn BindingIssue::name(self : BindingIssue) -> String

    BindingKind

    source
    pub(all) enum BindingKind {
      TextValue
      ListValue
      AssociationValue
    } derive(Eq)

    Application-level value shape; sparse and dense composites share a shape.

    BindingKind::equal

    source
    fn BindingKind::equal(BindingKind, BindingKind) -> Bool

    BindingKind::not_equal

    source
    fn BindingKind::not_equal(x : BindingKind, y : BindingKind) -> Bool

    BindingReport

    source
    pub struct BindingReport {
      issues : Array[BindingIssue]
    }

    BindingReport::is_clean

    source
    fn BindingReport::is_clean(self : BindingReport) -> Bool

    BindingReport::issues

    source

    BindingReport::missing_count

    source
    fn BindingReport::missing_count(self : BindingReport) -> Int

    BindingRule

    source
    pub(all) struct BindingRule {
      name : String
      kind : BindingKind
      required : Bool
    }

    BoundTemplate

    source
    pub struct BoundTemplate {
      // private fields
    }

    A template with some values fixed in advance. Useful for per-client base paths or per-tenant URI prefixes that recur across many requests.

    BoundTemplate::expand

    source
    fn BoundTemplate::expand(self : BoundTemplate, dynamic : Array[(String, Value)], max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[String, ExpandError]

    Supply request-local bindings to a partially bound template. Fixed values are never overridden. The usual expansion budgets apply to the combined set.

    BoundTemplate::fixed_names

    source
    fn BoundTemplate::fixed_names(self : BoundTemplate) -> Array[String]

    BoundTemplate::measure

    source
    fn BoundTemplate::measure(self : BoundTemplate, dynamic : Array[(String, Value)], max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[Int, ExpandError]

    Measure a partially bound expansion before constructing its URI text.

    CatalogAudit

    source
    pub struct CatalogAudit {
      entries : Array[CatalogEntryAudit]
      total_findings : Int
    }

    Policy findings for every catalog entry, preserving catalog order.

    CatalogAudit::entries

    source

    CatalogAudit::is_clean

    source
    fn CatalogAudit::is_clean(self : CatalogAudit) -> Bool

    CatalogAudit::total_findings

    source
    fn CatalogAudit::total_findings(self : CatalogAudit) -> Int

    CatalogBatchError

    source
    pub(all) enum CatalogBatchError {
      TooManyRequests
      TotalOutputTooLong
      InvalidRequest(Int, CatalogExpandError)
    }

    CatalogBatchError::code

    source
    fn CatalogBatchError::code(self : CatalogBatchError) -> String

    CatalogBatchError::index

    source
    fn CatalogBatchError::index(self : CatalogBatchError) -> Int?

    Zero-based request index when a catalog batch failed on one row.

    CatalogDiff

    source
    pub struct CatalogDiff {
      added : Array[String]
      removed : Array[String]
      changed : Array[CatalogTemplateChange]
    }

    CatalogDiff::added

    source
    fn CatalogDiff::added(self : CatalogDiff) -> Array[String]

    CatalogDiff::changed

    source

    CatalogDiff::is_empty

    source
    fn CatalogDiff::is_empty(self : CatalogDiff) -> Bool

    CatalogDiff::removed

    source
    fn CatalogDiff::removed(self : CatalogDiff) -> Array[String]

    CatalogEntryAudit

    source
    pub struct CatalogEntryAudit {
      name : String
      variable_count : Int
      expression_count : Int
      max_level : Int
      findings : Array[PolicyFinding]
    }

    Static analysis of one named template in a catalog.

    CatalogEntryAudit::expression_count

    source
    fn CatalogEntryAudit::expression_count(self : CatalogEntryAudit) -> Int

    CatalogEntryAudit::findings

    source

    CatalogEntryAudit::max_level

    source
    fn CatalogEntryAudit::max_level(self : CatalogEntryAudit) -> Int

    CatalogEntryAudit::name

    source
    fn CatalogEntryAudit::name(self : CatalogEntryAudit) -> String

    CatalogEntryAudit::variable_count

    source
    fn CatalogEntryAudit::variable_count(self : CatalogEntryAudit) -> Int

    CatalogError

    source
    pub(all) enum CatalogError {
      TooManyTemplates
      EmptyName
      DuplicateName(String)
      InvalidTemplate(String, ParseError)
    }

    Catalog compilation failure. Template syntax errors retain the entry name.

    CatalogError::code

    source
    fn CatalogError::code(self : CatalogError) -> String

    CatalogError::name

    source
    fn CatalogError::name(self : CatalogError) -> String?

    The offending catalog key when an error belongs to a specific entry.

    CatalogError::parse_error

    source
    fn CatalogError::parse_error(self : CatalogError) -> ParseError?

    The underlying RFC 6570 syntax error, including its source offset.

    CatalogExpandError

    source
    pub(all) enum CatalogExpandError {
      UnknownTemplate(String)
      InvalidBinding(String, ExpandError)
    }

    Expansion failure retains the catalog entry name when one was selected.

    CatalogExpandError::code

    source
    fn CatalogExpandError::code(self : CatalogExpandError) -> String

    CatalogExpandError::expand_error

    source

    CatalogExpandError::name

    source
    fn CatalogExpandError::name(self : CatalogExpandError) -> String

    CatalogJsonError

    source
    pub(all) enum CatalogJsonError {
      RootMustBeObject
      TemplateMustBeString(String)
      Compilation(CatalogError)
    }

    A JSON catalog manifest must map each endpoint name to one URI Template string. Key order is sorted for reproducible TemplateCatalog::names.

    CatalogJsonError::code

    source
    fn CatalogJsonError::code(self : CatalogJsonError) -> String

    CatalogJsonError::path

    source
    fn CatalogJsonError::path(self : CatalogJsonError) -> String

    CatalogJsonRenderError

    source
    pub(all) enum CatalogJsonRenderError {
      BindingConversion(JsonBridgeError)
      CatalogExpansion(CatalogExpandError)
    }

    CatalogJsonRenderError::code

    source

    CatalogRequest

    source
    pub(all) struct CatalogRequest {
      name : String
      bindings : Array[(String, Value)]
    }

    One named link request in a mixed catalog batch.

    CatalogTemplateChange

    source
    pub struct CatalogTemplateChange {
      name : String
      contract : TemplateDiff
    }

    A changed endpoint retains its contract comparison, including literal-only changes that a variable/operator comparison alone would not detect.

    CatalogTemplateChange::contract

    source

    CatalogTemplateChange::name

    source
    fn CatalogTemplateChange::name(self : CatalogTemplateChange) -> String

    ContractError

    source
    pub(all) enum ContractError {
      UnknownRule(String)
      DuplicateRule(String)
      IncompatibleRule(String)
      MissingRequired(String)
      WrongKind(String, BindingKind)
      InvalidBindings(ExpandError)
    }

    ContractTemplate

    source
    pub struct ContractTemplate {
      // private fields
    }

    Opt-in application contract. Unspecified variables retain RFC semantics.

    ContractTemplate::expand

    source
    fn ContractTemplate::expand(self : ContractTemplate, bindings : Array[(String, Value)], max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[String, ContractError]

    ContractTemplate::validate

    source
    fn ContractTemplate::validate(self : ContractTemplate, bindings : Array[(String, Value)], max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[Unit, ContractError]

    Validate shape, presence and ordinary expansion limits without rendering. Empty composites are undefined; an empty scalar is defined, as in RFC 6570.

    ExpandError

    source
    pub(all) enum ExpandError {
      DuplicateVariable(String)
      MissingVariable(String)
      UnusedVariable(String)
      InvalidValue(String)
      TooManyBindings
      ValueTooLong(String)
      TooManyItems(String)
      InvalidLimit(String)
      OutputTooLong
    }

    An expansion failure. The requested output limit is enforced before return.

    ExpandError::code

    source
    fn ExpandError::code(self : ExpandError) -> String

    Stable machine-readable code for an expansion error.

    ExpandError::message

    source
    fn ExpandError::message(self : ExpandError) -> String

    Human-readable explanation without embedding variable values.

    ExpressionInfo

    source
    pub(all) struct ExpressionInfo {
      start : Int
      end : Int
      operator : String
      level : Int
      variable_count : Int
      permits_reserved : Bool
    }

    One brace expression in the source template. Offsets are UTF-16 code units.

    JsonBridgeError

    source
    pub(all) enum JsonBridgeError {
      RootMustBeObject
      UnsupportedValue(String)
    }

    A JSON tree cannot be converted to URI Template values under this adapter. Only strings, null, arrays of strings/null, and objects of strings/null are accepted. Numeric and boolean coercion is deliberately left to callers.

    JsonBridgeError::code

    source
    fn JsonBridgeError::code(self : JsonBridgeError) -> String

    JsonBridgeError::path

    source
    fn JsonBridgeError::path(self : JsonBridgeError) -> String

    JsonRenderError

    source
    pub(all) enum JsonRenderError {
      Conversion(JsonBridgeError)
      Expansion(ExpandError)
    }

    The JSON adapter distinguishes conversion failures from URI expansion failures. A JSON number is never silently coerced to text.

    JsonRenderError::code

    source
    fn JsonRenderError::code(self : JsonRenderError) -> String

    JsonTemplateError

    source
    pub(all) enum JsonTemplateError {
      TemplateParse(ParseError)
      TemplateRender(JsonRenderError)
    }

    A single-call JSON expansion failed during syntax compilation or render.

    JsonTemplateError::code

    source
    fn JsonTemplateError::code(self : JsonTemplateError) -> String

    LinkChange

    source
    pub(all) struct LinkChange {
      name : String
      before : String
      after : String
    }

    LinkSession

    source
    pub struct LinkSession {
      // private fields
    }

    Immutable snapshot with a private dependency index and captured bindings.
    fn LinkSession::links(self : LinkSession) -> Array[(String, String)]

    LinkSession::total_length

    source
    fn LinkSession::total_length(self : LinkSession) -> Int

    LinkSession::update

    source
    fn LinkSession::update(self : LinkSession, patch : Array[BindingChange]) -> Result[LinkUpdate, LinkSessionError]

    Transactional patch: failure leaves this snapshot intact. Each affected endpoint is measured/rendered once, even if several variables change.

    LinkSessionError

    source
    pub(all) enum LinkSessionError {
      InvalidBudget
      TooManyChanges
      DuplicateChange(String)
      InvalidBindings(ExpandError)
      InvalidEndpoint(String, ExpandError)
      TotalOutputTooLong
    }

    LinkUpdate

    source
    pub struct LinkUpdate {
      // private fields
    }

    LinkUpdate::changes

    source
    fn LinkUpdate::changes(self : LinkUpdate) -> Array[LinkChange]

    LinkUpdate::recomputed

    source
    fn LinkUpdate::recomputed(self : LinkUpdate) -> Int

    LinkUpdate::session

    source
    fn LinkUpdate::session(self : LinkUpdate) -> LinkSession

    Operator

    source
    pub enum Operator {
      Simple
      Reserved
      Fragment
      Label
      Path
      PathParameter
      Query
      QueryContinuation
    }

    OutputSpan

    source
    pub(all) struct OutputSpan {
      source_start : Int
      source_end : Int
      output_start : Int
      output_end : Int
      is_expression : Bool
    }

    A source segment and the exact UTF-16 range it contributed to the output. Empty expressions still have a zero-width output range.

    ParseError

    source
    pub(all) enum ParseError {
      InputTooLong
      InvalidUnicode(Int)
      InvalidLiteral(Int)
      UnclosedExpression(Int)
      NestedExpression(Int)
      EmptyExpression(Int)
      InvalidOperator(Int)
      InvalidVariable(Int)
      InvalidModifier(Int)
      TooManyExpressions
      TooManyVariables
    }

    A parse failure with a UTF-16 code-unit offset into the template.

    ParseError::code

    source
    fn ParseError::code(self : ParseError) -> String

    Stable machine-readable code for a parse error.

    ParseError::message

    source
    fn ParseError::message(self : ParseError) -> String

    Human-readable explanation without embedding the source text.

    ParseError::offset

    source
    fn ParseError::offset(self : ParseError) -> Int?

    Return the UTF-16 code-unit offset of a parse error, if applicable.

    PolicyError

    source
    pub(all) enum PolicyError {
      InvalidFeatureLevel
      InvalidReferenceLimit
    }

    PolicyError::code

    source
    fn PolicyError::code(self : PolicyError) -> String

    PolicyFinding

    source
    pub(all) struct PolicyFinding {
      kind : PolicyFindingKind
      start : Int
      end : Int
    }

    UTF-16 source range of a static policy finding.

    PolicyFindingKind

    source
    pub(all) enum PolicyFindingKind {
      ReservedExpansion
      FragmentExpansion
      FeatureLevelExceeded(Int)
      ReferenceLimitExceeded
      RepeatedVariable(String)
    }

    PolicyFindingKind::code

    source
    fn PolicyFindingKind::code(self : PolicyFindingKind) -> String

    RenderedUri

    source
    pub struct RenderedUri {
      text : String
      spans : Array[OutputSpan]
    }

    Expanded URI text with a source-to-output map for diagnostics and tooling.

    RenderedUri::spans

    source
    fn RenderedUri::spans(self : RenderedUri) -> Array[OutputSpan]

    RenderedUri::text

    source
    fn RenderedUri::text(self : RenderedUri) -> String

    RequestAudit

    source
    pub struct RequestAudit {
      index : Int
      name : String
      unknown_template : Bool
      issues : Array[BindingIssue]
    }

    No values or expanded URIs are included in a request audit.

    RequestAudit::index

    source
    fn RequestAudit::index(self : RequestAudit) -> Int

    RequestAudit::issues

    source

    RequestAudit::name

    source
    fn RequestAudit::name(self : RequestAudit) -> String

    RequestAudit::unknown_template

    source
    fn RequestAudit::unknown_template(self : RequestAudit) -> Bool

    RequestAuditError

    source
    pub(all) enum RequestAuditError {
      RequestLimit
      BindingLimit
      FindingLimit
    }

    Segment

    source
    pub enum Segment {
      Literal(String)
      Expression(Operator, Array[VarSpec], Int, Int)
    }

    Template

    source
    pub struct Template {
      // private fields
    }

    A compiled template. Reuse it for many value sets.

    Template::analyze

    source
    fn Template::analyze(self : Template) -> TemplateAnalysis

    Template::bind

    source
    fn Template::bind(self : Template, bindings : Array[(String, Value)], max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[BoundTemplate, ExpandError]

    Capture validated bindings without retaining caller-owned mutable arrays. A bound name cannot be supplied again at expansion time.

    Template::check_policy

    source
    fn Template::check_policy(self : Template, policy : TemplatePolicy) -> Result[Array[PolicyFinding], PolicyError]

    Check a compiled template without bindings. All findings are returned in source order; a single expression may produce several distinct findings.

    Template::composite_capable_variables

    source
    fn Template::composite_capable_variables(self : Template) -> Array[String]

    Names that can accept a list or association value in every occurrence. This does not imply a composite is required; scalar values also work.

    Template::diff_contract

    source
    fn Template::diff_contract(self : Template, next : Template) -> TemplateDiff

    Compare variable and operator requirements before replacing a deployed template. Added variables matter to expand_required; newly scalar-only variables can reject previously valid composite bindings.

    Template::expand

    source
    fn Template::expand(self : Template, bindings : Array[(String, Value)], max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[String, ExpandError]

    Expand a precompiled template. The binding array rejects duplicate names so one name cannot silently change value during an expansion.

    Template::expand_detailed

    source
    fn Template::expand_detailed(self : Template, bindings : Array[(String, Value)], max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[RenderedUri, ExpandError]

    Expand while recording which source segment produced each output range. This has O(number of segments) additional memory compared with expand.

    Template::expand_json

    source
    fn Template::expand_json(self : Template, values : Json, max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[String, JsonRenderError]

    Convert a JSON object to ordered bindings and expand a compiled template. This is suitable for clients that already have a decoded JSON tree. It does not parse JSON text or validate a resulting network destination.

    Template::expand_many

    source
    fn Template::expand_many(self : Template, inputs : Array[Array[(String, Value)]], max_inputs? : Int, max_total_output? : Int, max_each_output? : Int) -> Result[Array[String], BatchError]

    Expand one compiled template for many independent value sets. The call is fail-fast and atomic: no partial result escapes on error. An aggregate output limit prevents an unbounded result even when each row is small.

    Template::expand_required

    source
    fn Template::expand_required(self : Template, bindings : Array[(String, Value)], reject_unused? : Bool, max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[String, ExpandError]

    Expand only when every referenced variable is bound. This opt-in policy is useful for fixed SDK operations; ordinary RFC 6570 expansion allows missing variables and remains available through Template::expand.

    Template::inspect_bindings

    source
    fn Template::inspect_bindings(self : Template, bindings : Array[(String, Value)]) -> BindingReport

    Inspect variable presence, duplicate bindings, and prefix/type conflicts without expanding or exposing any bound value in the report.

    Template::measure

    source
    fn Template::measure(self : Template, bindings : Array[(String, Value)], max_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[Int, ExpandError]

    Return the exact UTF-16 length of the expanded URI without constructing its output string. This performs the same binding checks as expand.

    Template::reference_count

    source
    fn Template::reference_count(self : Template, name : String) -> Int

    Count how often a variable occurs in this template.

    Template::source

    source
    fn Template::source(self : Template) -> String

    Return the original template text.

    Template::variable_profiles

    source
    fn Template::variable_profiles(self : Template) -> Array[VariableProfile]

    Derive an SDK-oriented variable schema from a compiled template. Profiles retain first-appearance order. A prefix modifier on any occurrence forces a scalar binding for that variable under this implementation.

    Template::variables

    source
    fn Template::variables(self : Template) -> Array[String]

    Return unique variable names in first-appearance order.

    Template::with_contract

    source
    fn Template::with_contract(self : Template, rules : Array[BindingRule], reject_unused? : Bool) -> Result[ContractTemplate, ContractError]

    TemplateAnalysis

    source
    pub struct TemplateAnalysis {
      expressions : Array[ExpressionInfo]
      uses : Array[VariableUse]
      max_level : Int
      has_reserved_expansion : Bool
    }

    Static summary of a compiled template. It does not inspect bound values.

    TemplateAnalysis::expressions

    source

    TemplateAnalysis::has_reserved_expansion

    source
    fn TemplateAnalysis::has_reserved_expansion(self : TemplateAnalysis) -> Bool

    True if '+' or '#' allows reserved characters from a value into the URI.

    TemplateAnalysis::max_level

    source
    fn TemplateAnalysis::max_level(self : TemplateAnalysis) -> Int

    Highest RFC 6570 feature level required by the template (1–4).

    TemplateAnalysis::uses

    source

    TemplateCatalog

    source
    pub struct TemplateCatalog {
      // private fields
    }

    A named set of precompiled templates for API endpoints or link relations.

    TemplateCatalog::audit

    source

    Audit every named template for SDK or server startup checks. The audit never reads values or produces URI text. An invalid policy is rejected even when the catalog contains no templates.

    TemplateCatalog::contains

    source
    fn TemplateCatalog::contains(self : TemplateCatalog, name : String) -> Bool

    TemplateCatalog::diff_catalog

    source
    fn TemplateCatalog::diff_catalog(self : TemplateCatalog, next : TemplateCatalog) -> CatalogDiff

    Compare two endpoint catalogs before deploying a new API/link definition. Additions and changes follow the next catalog order; removals follow the old. A report is structural evidence, not a proof of backward compatibility.

    TemplateCatalog::expand

    source
    fn TemplateCatalog::expand(self : TemplateCatalog, name : String, bindings : Array[(String, Value)], max_output? : Int) -> Result[String, CatalogExpandError]

    Expand one named template with a supplied value set. The catalog itself is immutable after compilation and can be reused across requests.

    TemplateCatalog::expand_json

    source
    fn TemplateCatalog::expand_json(self : TemplateCatalog, name : String, values : Json, max_output? : Int) -> Result[String, CatalogJsonRenderError]

    Render a named URI using a conservative JSON binding object. This method shares the same string/null/array/object conversion as expand_json.

    TemplateCatalog::expand_requests

    source
    fn TemplateCatalog::expand_requests(self : TemplateCatalog, requests : Array[CatalogRequest], max_requests? : Int, max_total_output? : Int, max_each_output? : Int) -> Result[Array[String], CatalogBatchError]

    Expand a mixed set of catalog entries in request order. A failure returns the failing request index; no partial collection is returned to the caller.

    TemplateCatalog::get

    source
    fn TemplateCatalog::get(self : TemplateCatalog, name : String) -> Template?

    Look up the original compiled template for analysis or specialized limits.

    TemplateCatalog::inspect_requests

    source
    fn TemplateCatalog::inspect_requests(self : TemplateCatalog, requests : Array[CatalogRequest], max_requests? : Int, max_bindings? : Int, max_findings? : Int) -> Result[Array[RequestAudit], RequestAuditError]

    Inspect every mixed request without stopping at the first unknown endpoint or binding issue. Missing variables are informational under RFC 6570. Limits apply to the complete input and result; failures return no partial audit.

    TemplateCatalog::measure

    source
    fn TemplateCatalog::measure(self : TemplateCatalog, name : String, bindings : Array[(String, Value)], max_output? : Int) -> Result[Int, CatalogExpandError]

    Measure the exact output size of a named template without rendering it.

    TemplateCatalog::measure_requests

    source
    fn TemplateCatalog::measure_requests(self : TemplateCatalog, requests : Array[CatalogRequest], max_requests? : Int, max_total_output? : Int, max_each_output? : Int) -> Result[Int, CatalogBatchError]

    Measure a mixed catalog batch without constructing the URI outputs. The result is the exact total output length under the same per-request and aggregate limits used by expand_requests.

    TemplateCatalog::names

    source
    fn TemplateCatalog::names(self : TemplateCatalog) -> Array[String]

    TemplateCatalog::start_session

    source
    fn TemplateCatalog::start_session(self : TemplateCatalog, bindings : Array[(String, Value)], max_each_output? : Int, max_total_output? : Int, max_bindings? : Int, max_value_length? : Int, max_items? : Int) -> Result[LinkSession, LinkSessionError]

    Capture shared bindings and generate every endpoint once. Unknown bindings are rejected; missing variables retain ordinary RFC omission semantics.

    TemplateCatalog::templates_using

    source
    fn TemplateCatalog::templates_using(self : TemplateCatalog, variable : String) -> Array[String]

    List templates that reference one variable, in catalog order. API schema tooling can use this reverse lookup to identify which links may need new bindings when a field is renamed or removed.

    TemplateDiff

    source
    pub struct TemplateDiff {
      added_variables : Array[String]
      removed_variables : Array[String]
      became_scalar_only : Array[String]
      new_repeated_variables : Array[String]
      old_level : Int
      new_level : Int
      reserved_added : Bool
      fragment_added : Bool
    }

    Structural changes between two compiled templates. This is a source-level report for API reviews, not a proof that two templates render equivalent URIs or that a deployment is backward compatible.

    TemplateDiff::added_variables

    source
    fn TemplateDiff::added_variables(self : TemplateDiff) -> Array[String]

    TemplateDiff::became_scalar_only

    source
    fn TemplateDiff::became_scalar_only(self : TemplateDiff) -> Array[String]

    TemplateDiff::fragment_added

    source
    fn TemplateDiff::fragment_added(self : TemplateDiff) -> Bool

    TemplateDiff::has_flagged_changes

    source
    fn TemplateDiff::has_flagged_changes(self : TemplateDiff) -> Bool

    TemplateDiff::new_level

    source
    fn TemplateDiff::new_level(self : TemplateDiff) -> Int

    TemplateDiff::new_repeated_variables

    source
    fn TemplateDiff::new_repeated_variables(self : TemplateDiff) -> Array[String]

    TemplateDiff::old_level

    source
    fn TemplateDiff::old_level(self : TemplateDiff) -> Int

    TemplateDiff::removed_variables

    source
    fn TemplateDiff::removed_variables(self : TemplateDiff) -> Array[String]

    TemplateDiff::reserved_added

    source
    fn TemplateDiff::reserved_added(self : TemplateDiff) -> Bool

    TemplateError

    source
    pub(all) enum TemplateError {
      Parse(ParseError)
      Expand(ExpandError)
    }

    A single-use expansion failed while parsing or while applying values.

    TemplatePolicy

    source
    pub(all) struct TemplatePolicy {
      allow_reserved : Bool
      allow_fragment : Bool
      max_level : Int
      max_references : Int
      forbid_repeated_variables : Bool
    }

    Static restrictions for an application that consumes URI templates. This checks template structure only; it cannot validate a final URI host.

    Value

    source
    pub(all) enum Value {
      Scalar(String)
      List(Array[String])
      Assoc(Array[(String, String)])
      SparseList(Array[String?])
      SparseAssoc(Array[(String, String?)])
    }

    A value supplied to an RFC 6570 variable. Associative entries retain order.

    VarSpec

    source
    pub struct VarSpec {
      name : String
      prefix : Int?
      explode : Bool
      start : Int
      end : Int
    }

    VariableProfile

    source
    pub(all) struct VariableProfile {
      name : String
      occurrences : Int
      first_start : Int
      last_end : Int
      scalar_only : Bool
      uses_explode : Bool
      uses_reserved : Bool
      uses_query : Bool
      maximum_prefix : Int?
    }

    Aggregate requirements for one variable across all uses in a template. RFC 6570 variables remain optional unless the caller uses expand_required.

    VariableUse

    source
    pub(all) struct VariableUse {
      name : String
      start : Int
      end : Int
      expression_index : Int
      operator : String
      prefix : Int?
      explode : Bool
    }

    One occurrence of a variable specification, including its modifier.

    bindings_from_json

    source
    fn bindings_from_json(input : Json) -> Result[Array[(String, Value)], JsonBridgeError]

    Convert a JSON object to ordered bindings. Object keys are sorted so associative expansion is deterministic across MoonBit backends.

    compile_catalog

    source
    fn compile_catalog(entries : Array[(String, String)], max_templates? : Int, max_template_length? : Int) -> Result[TemplateCatalog, CatalogError]

    Compile every catalog entry once. Names remain in caller order. Duplicate names are rejected so a later template cannot silently replace an earlier endpoint or link relation.

    compile_catalog_json

    source
    fn compile_catalog_json(input : Json, max_templates? : Int, max_template_length? : Int) -> Result[TemplateCatalog, CatalogJsonError]

    Build a named catalog from an already-decoded JSON object. JSON parsers may have discarded duplicate object keys before this method is called; callers that reject duplicates must enforce that while reading JSON text.

    expand

    source
    fn expand(source : String, bindings : Array[(String, Value)], max_output? : Int) -> Result[String, TemplateError]

    Parse and expand a template once. Use parse and Template::expand when the same template is expanded repeatedly.

    expand_json

    source
    fn expand_json(source : String, values : Json, max_output? : Int) -> Result[String, JsonTemplateError]

    Parse a template and expand it from a JSON object in a single call.

    parse

    source
    fn parse(input : String, max_length? : Int, max_expressions? : Int, max_variables? : Int, strict_literals? : Bool) -> Result[Template, ParseError]

    Compile an RFC 6570 Level 4 URI Template. Limits and error offsets are measured in UTF-16 code units.

    permissive_policy

    source
    fn permissive_policy() -> TemplatePolicy

    Policy matching the syntactic capabilities of this library.

    value_from_json

    source
    fn value_from_json(input : Json, path? : String) -> Result[Value?, JsonBridgeError]

    Convert one JSON value. JSON null is an undefined variable or member.

    version

    source
    fn version() -> String

    Semantic version of this source checkout.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io