# SANSA v1 Addressing Scope: structural address model and selector vocabulary for SANSA v1. ## 1. Overview SANSA addressing defines a deterministic notation for identifying semantic bindings in a semantic address namespace. An address describes structure. It does not, by itself, require traversal, execution, mutation, authorization, or value evaluation. Those responsibilities belong to a resolving consumer, SANSA.Resolve, SANSA.Query, or another capability layered above the address model. SANSA is namespace- and domain-neutral. SANSA defines only how semantic locations are expressed. It does not define what those locations represent. A SANSA address may identify AEON bindings, RDF-like graph terms, database entities, service resources, runtime objects, filesystem nodes, or any other semantic namespace exposed by a resolver. AEON documents may embed SANSA address literals, and AEON-backed consumers may resolve them against the AEON binding model and canonical paths. The address language itself is not limited to AEON. SANSA member selectors describe semantic traversal rather than object traversal. For example, a non-AEON semantic namespace could expose RDF-like bindings through ordinary SANSA member selectors: ```text $.["john"].isLocatedAt.["Brussels"] ``` Whether `john`, `isLocatedAt`, and `Brussels` are AEON binding keys, RDF-like graph terms, database fields, service resources, filesystem nodes, runtime object properties, or another domain model is determined by the resolving namespace. ## 2. Terms A **namespace** is the addressable semantic structure exposed by a SANSA implementation. A **binding** is an addressable semantic unit exposed by a namespace. A **Binding Set** is an ordered collection of bindings. A **selector** is one navigation or filtering operation in an address expression. A **canonical address** is an exact address that identifies at most one binding in a namespace. An **address expression** may identify zero, one, or many bindings when resolved. It may contain parent traversal, expansion, filter, pattern, range, or local address-space selectors. ## 3. Lexical Model SANSA address expressions use a small ASCII structural grammar outside quoted payloads. Whitespace is not permitted outside quoted payloads. Bare identifiers use: ```ebnf Identifier ::= IdentifierStart IdentifierContinue* IdentifierStart ::= "A".."Z" | "a".."z" | "_" IdentifierContinue ::= IdentifierStart | "0".."9" ``` Position indexes use unsigned decimal notation without leading zeroes: ```ebnf Index ::= "0" | NonzeroDigit Digit* NonzeroDigit ::= "1".."9" Digit ::= "0".."9" PositionRange ::= "[" [Index] ".." [Index] "]" ``` Position ranges must include at least one endpoint. Negative endpoints and leading zeroes are not valid. Position indexes and position range endpoints are bounded by the implementation. SANSA v1 portable implementations must support at least one million addressable positions, expressed as index values from `0` through `999999` inclusive. Values above `999999` are implementation-defined and non-portable: an implementation may accept a larger configured maximum or reject them with `SANSA_POSITION_INDEX_LIMIT_EXCEEDED`. Implementations that accept values above the portable maximum index SHOULD surface `SANSA_NON_PORTABLE_POSITION_INDEX` through a non-fatal diagnostic channel when available. The warning should identify the observed index or endpoint and the portable maximum index. Quoted member names, local address-space names, name patterns, and quoted qualifier arguments use AEON double-quoted string payload rules. This allows characters that are not part of the bare ASCII selector grammar to be carried without making address parsing context-sensitive. ### 3.1 Qualified Address Literals A qualified address literal is an address expression followed by an optional qualifier expression. ```ebnf QualifiedAddressLiteral ::= AddressExpression [ ":" QualifierExpression ] QualifierExpression ::= QualifierTerm ( "|" QualifierTerm )* QualifierTerm ::= QualifierTypeName QualifierParameterGroup* QualifierArgumentGroup* QualifierTypeName ::= Identifier QualifierParameterGroup ::= "<" QualifierTypeParameter ( "," QualifierTypeParameter )* ">" QualifierTypeParameter ::= QualifierTerm QualifierArgumentGroup ::= "[" QualifierArgument "]" QualifierArgument ::= QualifierArgumentToken | DoubleQuotedPayload QualifierArgumentToken ::= QualifierArgumentChar+ QualifierArgumentChar ::= "A".."Z" | "a".."z" | "0".."9" | "!" | "#" | "$" | "%" | "&" | "*" | "+" | "-" | "." | ":" | ";" | "=" | "?" | "@" | "^" | "_" | "|" | "~" | "<" | ">" ``` SANSA owns this qualifier grammar. Host implementations define the accepted qualifier surface. SANSA Addressing assigns no semantics to qualifier expressions. Host implementations validate the syntax and qualifier surface they support, preserve accepted qualifier structure, and may reject qualifier forms they do not understand. Consumers decide whether to interpret, ignore, or reject accepted qualifiers. Examples: ```text $.result:number|nan $.inventory:list $.inventory:csv[","] $.path:tuple $.value:type["arg"] ``` The `|` operator is only valid at the top level of a qualifier expression. Nested qualifier unions are not valid in SANSA v1: ```text $.value:list ``` Qualifier parameter groups are repeatable. This permits embeddings that avoid raw comma syntax in contexts where comma has host-language meaning: ```text $.path:tuple ``` SANSA also permits comma-separated parameters inside one parameter group: ```text $.path:tuple ``` Host implementations may prefer or require the repeated-group form if that better fits their parser. Qualifier clarifiers use a single optional bracketed list. Values in the list are quoted strings or numbers. String clarifiers must be quoted: ```text $.key:string[","] $.key:string[",","."] $.bits:radix[16] ``` Repeated clarifier lists and unquoted string clarifiers are not valid SANSA v1 address literals: ```text $.key:string[","]["."] $.version:sep[.] ``` More complex payloads use quoted-string syntax: ```text $.inventory:csv[","] $.field:separator["::"] $.line:terminator["\r\n"] ``` These examples are syntactically valid SANSA. A host implementation may still reject them if they are outside the qualifier surface it accepts. ### 3.2 AST Shape Parsers should expose qualifier structure rather than treating it only as an opaque string. ```text QualifiedAddress address qualifierExpression? QualifierExpression terms[] QualifierTerm typeName parameterGroups[] argumentGroups[] ``` Implementations may also expose flattened convenience views, but repeated parameter and argument groups must remain recoverable from the parse tree. ## 4. Address Roots ### 4.1 Absolute Root The absolute root is written: ```text $ ``` It means: > Begin from the primary root supplied by the resolving consumer. Examples: ```text $.contact.name $.contacts[0] $.message.@.id ``` ### 4.2 Contextual Root The contextual root is written: ```text ? ``` It means: > Begin from the contextual root supplied by the resolving consumer. Examples: ```text ?.name ?.address.city ?.items[0] ``` Contextual-root expressions are structurally valid without a context, but they cannot be resolved unless the consumer supplies one. ### 4.3 Relative Selector Fragments Some consumers, including SANSA.Query, allow selector fragments that begin with a selector rather than a root: ```text .name .roles.* .@.metadata ``` Such fragments are not complete absolute addresses. Their starting point is supplied by the consuming capability. ## 5. Exact Selectors Exact selectors preserve a path that can identify at most one binding. ### 5.1 Named Binding ```text .name ``` Selects a direct named child binding. Names that cannot be written safely in bare form use a quoted member segment: ```text .["member.with.dots"] .["spaced name"] ``` ### 5.2 Positional Binding ```text [0] [12] ``` Selects the binding at the specified zero-based position in the ordered sequence exposed by the current binding. Positional syntax is representation independent. It does not itself distinguish lists, tuples, nodes, or implementation-specific ordered structures. Chained positional selectors are syntactically valid: ```text $.matrix[2][2] ``` Whether an intermediate binding is indexable is a resolution or schema question, not a lexical-addressing question. ### 5.3 Position Range ```text [2..5] [2..] [..5] ``` Selects a contiguous inclusive range of positional children exposed by the current binding. Open start means position `0`. Open end means through the final exposed positional child. A range with both endpoints omitted is invalid: ```text [..] ``` If `start > end`, resolution produces an empty Binding Set rather than a diagnostic. Both endpoints, when present, must be within the implementation's configured position index maximum. The SANSA v1 portable maximum index is `999999`, representing one million addressable positions from `0` through `999999`; endpoints above that value are valid only for implementations that explicitly support them and should carry `SANSA_NON_PORTABLE_POSITION_INDEX` when accepted. Position ranges are selector expressions, not exact selectors. An address expression containing a position range is therefore not a canonical address, even when the range happens to resolve to one binding. Position range syntax is representation independent. Lists, tuples, nodes, and other host structures may expose ordered positional children, but whether a binding has meaningful ordered positional children is a profile or host decision. ### 5.4 Attribute Address Space ```text .@ ``` Enters the attribute address space of the current binding. Once inside the attribute address space, ordinary SANSA navigation applies. Examples: ```text $.message.@.id $.message.@.properties.caller.@.by ``` Compact forms such as `$.message@id` are not valid SANSA v1 address syntax. Attribute-space traversal uses the explicit `.@.` segment so attributes remain unambiguous from ordinary member names. ### 5.5 Local Address Space ```text .<"namespace"> ``` Enters a named local address space at the current resolution point. Examples: ```text $.document.<"sections">.introduction $.page.<"html-id">.navigation $.<"params">.username $.<"session">.user_id ``` A local address-space segment identifies an address-space transition, not an ordinary child binding. Therefore these two addresses are not equivalent: ```text $.document.contact $.document.<"contact"> ``` The first selects an ordinary child named `contact`. The second enters a local address space named `contact`. ## 6. Non-Exact Selectors Non-exact selectors may produce zero or more bindings or depend on resolver context beyond a fixed canonical path. ### 6.1 Parent Selector ```text .^ ``` Moves from the current binding to its exposed parent binding. Examples: ```text ?.^.id ?.^.sibling $.inventory.items[2].^.metadata ``` The parent selector is a selector, not part of a fixed canonical address. An address expression containing `.^` is therefore non-canonical even when it resolves to exactly one binding. The caret character is not a bare member selector. A binding literally named `^` remains addressable with a quoted member selector: ```text .["^"] ``` Parent traversal must be explicitly exposed and authorized by the resolving consumer. It must not bypass local address-space, attribute address-space, profile, or capability boundaries. ### 6.2 Direct Expansion ```text .* ``` Expands all direct child bindings of the current binding. ### 6.3 Descendant Expansion ```text .** ``` Expands descendants reachable through the ordinary value hierarchy. The current binding is not included. Attribute address spaces and local address spaces are not traversed implicitly. They require explicit selectors. ### 6.4 Name Pattern Selector ```text .("id-*") .("*-id") .("*id*") .("item-??") ``` Name patterns match complete binding names. | Operator | Meaning | | :--- | :--- | | `*` | zero or more characters | | `?` | exactly one character | *SANSA name-pattern selector operators* Within the decoded pattern payload, a backslash escapes literal wildcard characters. `\*` matches a literal asterisk, `\?` matches a literal question mark, and `\\` matches a literal backslash. Because name patterns are written inside AEON double-quoted payloads, the source spelling uses AEON string escaping first: ```text .("item\\*") matches item* .("item\\?") matches item? ``` The underscore character `_` has no wildcard meaning in name patterns; it is matched as an ordinary name character. Regular expressions are intentionally excluded from SANSA v1 addressing. ## 7. Filter Selectors Filter selectors filter the current Binding Set. They do not evaluate values. ### 7.1 Semantic Type Filter ```text #type ``` Filters by semantic datatype identity. Example: ```text $.content.*#text ``` ### 7.2 Representation Kind Filter ```text %kind ``` Filters by representation kind. Example: ```text $.content.*%stringLiteral ``` Semantic datatype and representation kind are distinct. ```aeon content = { a:text = "I am text" b:string = "I am string" } ``` The expression `$.content.*#text` selects only `a`. The expression `$.content.*%stringLiteral` selects both `a` and `b`. ## 8. Canonical Addresses Canonical addresses identify at most one binding. Examples: ```text $ $.member $.["member.with.dots"] $.list[0] $.message.@.id $.message.@.properties.caller.@.by ``` Expanded address expressions are not canonical addresses, even though each binding produced by such an expression has its own canonical address. Examples of non-canonical address expressions: ```text $.users.* $.content.*#text $.content.("id-*") $.items[2..5] $.items[2].^ $.** ``` Qualified address literals have a canonical address component and a qualifier component. Canonical rendering preserves repeated qualifier parameter and argument group boundaries. ## 9. Local Address-Space Boundaries Local address spaces are isolated scopes. A local address space may only be entered through an explicit local address-space selector: ```text .<"namespace"> ``` There is no fallback between primary and local address spaces. A reference to `$.<"params">.username` must not fall back to `$.params.username`. Traversal must not cross a local address-space boundary implicitly. SANSA v1 defines no parent selector that can leave a local address space. Local address spaces exist only when explicitly exposed or mounted by the resolving consumer, environment, or addressed resource. A syntactically valid local address-space selector does not imply authorization to resolve that space. ## 10. Opaque Local Semantics SANSA standardizes the transition into a named local address space. It does not standardize the internal meaning of every local namespace. Examples of possible local address spaces include: - query parameters - session data - request data - sections exposed by an embedded document processor - HTML identifiers exposed by an HTML processor - named destinations exposed by a PDF processor - application-defined resource views The provider of a local address space owns its internal semantics, subject to SANSA resolution rules and consumer policy. ## 11. Superseded Anchor Form Earlier design notes explored postfix anchor selectors such as: ```text $.document<"contact"> ``` SANSA v1 proposals prefer the local address-space segment: ```text $.document.<"contact"> ``` The local address-space form makes the transition explicit as a selector and allows additional navigation within the local space. ## 12. Relationship to AEON Literals The SANSA address model is independent of AEON Core syntax. AEON may define a native SANSA address literal based on this grammar. When used as an AEON literal, a SANSA address remains declarative. AEON Core is expected to validate structural syntax and transport the value, not resolve the address or evaluate query semantics. AEON is one host implementation of SANSA address literals. It may restrict the qualifier surface it accepts while still using the broader SANSA grammar as the address-language foundation. ## 13. Parser Requirements Conforming SANSA Address parsers must reject: - whitespace outside quoted payloads - invalid bare identifiers - empty quoted member names - empty local address-space names - position indexes with leading zeroes - invalid quoted payload escapes - unterminated or malformed qualifier syntax - empty qualifier parameter or argument groups - nested qualifier unions Parsers must not assign semantic meaning to qualifier terms as part of address parsing. Semantic interpretation belongs to the host implementation or consuming capability. --- ## Related documents - [SANSA.Resolve v1](./sansa-v1-resolve.md) - [SANSA.Query v1](./sansa-v1-query.md)