@valos/plot library workspace

A vplot is a generic, hierarchically structured string with a character set that is untransformed by encodeURIComponent(). The vplot structure expresses sequential dependencies, parameter lists, nesting, term/data pairs and arbitrary data encoding. The vplot strings themselves are meaning-agnostic: the semantics are provided by the specific vplot processors.

In ValOS context vplots are used as resource identifiers, valospace queries, but also as a deterministic JSON serialization, an intermediate language for computation, a configuration language, JSON-LD integration glue and more.

VPlot together with and form the infrastructural foundation ie. the fabric of the valospace.

This document is part of the library workspace @valos/plot (of domain @valos/kernel) which has the description: `Specifies the hierarchical ValOS plot string format and the 'VPlot' namespace`.

A subset of VPlots called 'vrids' contain a fixed starting point and identify valospace resources.

VPlots contain 'context terms' which refer to definitions provided by the surrounding context, usually as references to some external ontology. This allows VPlot semantics to be extended in domain specific but reusable manner.

The primary example of a VPlot context is the JSON-LD @context of a ValOS event chronicle which provides the semantics for all VPlots that appear inside the chronicle.

§ VPlot structure

VPlot grammar only adds "@" and "$" in addition to encodeURIComponent characters. VPlot grammar has two primary building blocks: vsteps and vparams.

A VPlot itself is an ordered sequence of "@"-separated vsteps, each of which logically depends on the preceding one.
A vstep can have a 'verb type' and a sequence of vparams, all logically independent of each other.
A vparam always contains a "$"-prefix. The vparam then has an optional context-term and finally a "."-prefixed vvalue.

VPlots serve two superficially distinct purposes as paths and as identifiers. If the first vstep of a VPlot begins with a context term (ie. doesn't have a verb type) then the whole VPlot is valospace resource identifier (a *VRID*) and the first vstep is a valospace global resource identifier (a *VGRID*).

§ Main VPlot rules

  vplot = "@" *(vstep "@") "@"
  vstep  = [ verb-type ] *vparam
  vparam = "$" [ context-term ] "." vvalue
  vvalue = vplot / "$" / 1*( unencoded / pct-encoded )

§ VPlot with a VGRID is a resource identifier: a VRID

A VPlot with a first vstep lacking a verb type and no other vsteps identifies a global resource.

Many valospace resources, so called *fixed sub-resources* are identified by a fixed path from the global resource defined by the same verbs that define non-VRID VPlots. Thus while paths and identifiers are superficially different it is useful to represent them both using the same VPlot verb structure.

Both verb and VGRID params can also have context term references to an external lookup of URI prefixes and semantic definitions.

§ VPlot representations

The canonical VPlot is a string, but there are other format specific representations.

§ VPlot URN-scheme (tentative)

A VRID VPlot string can be expressed as an URN by removing the "@" prefix and the "@@" suffix and then prefixing the string with `urn:valos:`.

Editorial Note: the urn:valos is fully speculative as of 2019-11. On one hand there is salient overlap between valos VRID and URN principles: URN calls for structured and managed process of name assignment and resolution and VRID system is precisely that. On the other hand VRID defers a lot of detail to specific VGRID format-term specifications which might prove problematic for actual standardization process. It is possible that instead of a generic urn:valos namespace there would be specific urn namespaces for specific VRID formats (e.g. urn:valos-u4, urn:valos-cc) or that urn:valos would stand for one specific format (which would most likely be the ~cc).

§ Segmented VPlot representation

Segmented VPlot is a recursive partitioning of a VPlot as a JSON object where each structural segment is expressed as an array. The first entry of each such segment is a string which denotes the segment type and the remaining entries contain the segment payload:

"@" identifies a VPlot segment with remaining entries as step segments
"$" identifies a vparam segment with its second entry being a valid context term string and an optional third entry containing the vvalue
"$." identifies a vparam segment without a context-term and with an optional second entry containing the vvalue
otherwise the segment type denotes the verb type of a verb segment and remaining entries containing the parameter segments

JSON numbers and strings can only appear as param values of "$" or "$."-segments. JSON objects cannot appear. A VPlot which is used as a contextless param of a verb must appear directly without intermediate "$."-segments (unlike in the string VPlot construct). Conversely a verb used as a contextless param must still be wrapped inside a "@"-segment.

§ Shortcut VPlot representation

Shortcut VPlot format is a compact object representation of a VPlot as 'human readable' JSON which can then be distributed to the canonical representation. In fact any JSON construct is a valid shortcut VPlot, and as long as all initial array entries equal to "@", "$" and "$." are escaped as ["$.", "@"], ["$.", "$"] and ["$.", "$."] the shortcut segment will resolve back into the original JSON construct.

§ Cemented VPlots

VPlots contain context references but do not _contain_ knowledge about the context. This is to ensure that a VPlot can be moved from a context to a compabible one without modification.

Cementing a VPlot with a context inside an environment produces a construct where the VPlot itself and specifically its context terms are converted to their environment-specific representations. This representation can be anything from interpretable JSON to fully compiled executable code.

Cementing also performs the security critical function of validating the context terms and their parameters against their context inside that particular environment (e.g. a typical validation failure being the lack of implementation for a specific context term by the environment).

§ VPlot semantics

The full semantics of a particular VPlot string in some environment comes from several different sources:

VPlot specification (ie. this document) fully specifies the VPlot structure and grammar and defines several verb types
VPlot extension specifications can define additional conforming verb type semantics
VPlot environment can define context terms directly
VPlot environment can delegate context term definitions to external ontologies

§ VPlot equivalence follows URN equivalence

Two VPlots identify the same path (and in case they're VRIDs, refer to the same resource) iff their URN representations are urn-equivalent and 1. they either share the same environment or 2. their corresponding context terms expand to URIs which are pair-wise URI-equivalent.

For the general case the actual semantics of a VPlot and specifically of its context-term's depends on the context it is used. Vrids have a fixed context which is established by the VGRID. This has implications on VRID equivalence.

§ 'context-term' is a lookup to definitions provided by the context

A VPlot can be contextual via the vparam context-term's. These are case-sensitive strings with very restricted grammar. The context where the VPlot is used defines the exact meaning of these terms. The meaning for two identical context-terms is recommended to be uniform across domains where possible. A VPlot is invalid in contexts which don't have definitions for the context-terms of all of its steps. This gives different contexts a fine-grained mechanism for defining the vocabularies that are available.

Idiomatic example of such context is the event log and its JSON-LD context structure which is to define both URI namespace prefixes as well as available semantics.

§ 'vvalue' carries content

*vparams* is a sequence of vparam's, optionally prefixed with "$" and a context-term. The idiomatic vvalue is a string. If present a context-term may denote a URI prefix in which case the vvalue forms the suffix of the full expanded URI reference. However contexts are free to provide specific semantics for specific context-terms, such as interpreting them as the value type of the vvalue etc.

"$" for a vvalue denotes empty string.

*vvalue* both allows for fully unencoded nesting of VPlot's as well as allows encoding of all unicode characters in percent encoded form (as per encodeURIComponent)

§ Semantic design choices and guidelines

As VPlot structure is expressive there are often multiple ways to express a particular design need. Following juxtapositions and guidelines apply:

"vsteps vs. vparams" or "How should I express a sequence?": If the entries of a sequence depend on each other (e.g. in a query or in an execution list) they are vsteps, if not (e.g. data entries) they are vparams of a vstep.
"verb type vs. context term" or "How should I express a concept?": If the concept is interaction logic, domain specific, visible to the end-users or it doesn't require infrastructure code changes it is probably a context term with URI expansion to some ontology. If the concept concerns VPlot structure or its interpretation and is generic enough to warrant a specification and corresponding infrastructure implementation work it is possibly a verb type with new extension spec or new release of an existing spec.
"!-computational vs. declarational" or "Who writes the code?": Computational vsteps (those with verb type beginning with "!") allow for turing-complete computation to be embedded inside VPlots. An environment that chooses to support these verbs and context terms has the upside of rapid and arbitrarily expressive configurability without further code changes. The downside is that security and complexity analysis becomes intractable even more rapidly. Declarational vsteps (all other verb types) require explicit interpretation but should be preferred when meaningful semantics can be specified.

§ verb - a vstep from a source resource to target resource(s)

A verb is a one-to-maybe-many relationship between resources. A verb can be as simple as a trivial predicate of a triple or it can represent something as complex as a fully parameterized computational function call.

§ Informative verb rules

  vverb        = verb-type *vparam
  vparam       = "$" [ context-term ] "." vvalue
  verb-type    = 1*unencoded
  context-term = ALPHA *unreserved-nt
  vvalue       = vplot / "$" / 1*( unencoded / pct-encoded )

A verb is made up of verb type and a sequence of vparams. The grammar of verb-type is restricted but less than for context-term. The verb type semantics is always fixed. Because of this the first vparam may be semantically special and act as a contextual name of the verb.

§ verb-type

*verb-type* specifies the relationship category between the segment host resource and sub-resource, a set of inferred triples as well as other possible constraints.

§ verb type "`.`": property or ScopeProperty selector

Verb for selecting the resource (typically a ScopeProperty) with the given name and which has the head as its scope.

§ Property selector example
Triple pattern `?s <urn:valos:.$.myProp> ?o` matches like:
?o V:scope ?s ; V:name "myProp"
Mnemonic: '.' is traditional property accessor (ie. ScopeProperty).

§ verb type "`*`": sequence or Relation selector

Verb for selecting all resources (typically Relations) with the given name and which have the head as their source.

§ Sequence selector example
Triple pattern `?s <urn:valos:-out--$.PERMISSIONS> ?o` matches like:
?o V:source ?s ; V:name "PERMISSIONS"
Mnemonic: '*' for many things as per regex/glob syntax (Relations are the only things that can have multiple instances with the same name).

§ verb type "`+`": container or Entity selector

Verb for selecting the resource (typically an Entity) with the given name and which has the head as their container.

§ Container selector example
Triple pattern `?s <urn:valos:*$.Scripts> ?o` matches like:
?o V:parent ?s ; V:name "Scripts"
Mnemonic: "+" is a list-view symbol of an expandable container.

§ verb type "`~`": content or Media selector

Verb for selecting the Media with the given name which has the head as their folder.

§ Content selector example
Triple pattern `?s <urn:valos:~$.foo.vs> ?o` matches like:
?o V:folder ?s ; V:name "foo.vs"
Mnemonic: "~" has no mnemonic yet.

§ verb type "`.O`": object or target selector

Verb that is a synonym for predicate 'rdf:object'.

§ Property selector example
Triple pattern `?s <urn:valos:.O> ?o` matches like:
?s rdf:object ?o
Mnemonic: follow line '-' to target.

§ verb type "`_`": subspace selector

Verb for selecting named subspaces and ghosts.

§ Language subspace selector example
Triple pattern `?s <urn:valos:.$.myProp@_$lang.fi> ?o` matches like:
?_sp V:scope ?s ; V:name "myProp" . ?o V:subspacePrototype* ?_sp ; V:language "fi"
Mnemonic: '_' is underscore is subscript is subspace.

If the verb name context term is an identifier term then the subspace denotes the ghost subspace of the identified resource inside the current resource.

§ Ghost subspace selector example
Triple pattern `?s <urn:valos:_$~u4.ba54> ?o` matches like:
?o V:ghostHost ?s ; V:ghostOf <urn:valos:$~u4.ba54>
Mnemonic: The '_$~' is a 'subspace of ghoStS'.

§ verb type "`!`": computation evaluators

VPlots are data. In general whenever a representation of a VPlot appears in some evaluation context the representation evaluates into itself. The only exception are the verbs with `!` as the leading character of their type: these represent the class of computation evaluators.

VPlot spec tries to specify as little as possible. As such it doesn't specify an execution model itself but delegates this to context term ontologies. VPlot only provides a way to specify evaluation dependency chains and the mapping between VPlot data structures and evaluator inputs and outputs.

Following principles apply:

The different evaluator verb types only specify the means to access and process the VPlot data structure itself. These `evaluator types` are defined by the VPlot specification(s).
All computation (f.ex. flow control and method call) semantics are specified by the first vplot param of the evaluator verb, ie. the `computation id`. This specification shall be provided by the ontology that defines the context-term of the computation id param.
If the computation id doesn't have a context-term of if the specification denotes the computation id to be a `trivial name` then the computation is a `context scope lookup path`.
When a computation evaluator is evaluated all of its vparams are evaluated first in an order defined by the evaluation context and their results stores as evaluation arguments.
The evaluation context is then searched for an implementation for the evaluator type / computation id combination. If none is found the context does not implement the computation and the whole evaluation chain is rejected.
The evaluation implementation is resolved with the evaluation arguments and its result is the result of the computation evaluator.

Editorial Note: this section should be greatly improved. The purpose of computation verbs lies more on representing various conversions (as part of dynamic operations such as web API route mapping) and less on clever SPARQL trickery. The illustration here uses (questionable) SPARQL primarily for consistency.

§ Computation selector example
Triple pattern `?s <urn:valos:!$valk.add$number.10$.@!$.myVal@@> ?o` matches like:
?_:0 V:scope ?s ; V:name "myVal" ; V:value ?myVal . FILTER (?o === 10 + ?myVal)

§ VRID is a stable identifier of a global resource or a fixed sub-resource

A VRID is a VPlot which has VGRID as its first production (via vgrid-tail).

§ Informative VRID rules

  vrid        = "@" "$" vgrid "@" *(vstep "@") "@"
  vgrid       = format-term "." vgrid-value *vparam

§ VGRID identifies global resources - primary keys, free ownership, concrete state

The VGRID uniquely identifies a *global resource*. If a VRID contains a VGRID and no verbs this global resource is also the *referenced resource* of the VRID itself.

§ Informative VGRID rules

  vgrid         = format-term "." vgrid-value *vparam
  format-term   = "~" 1*unreserved-nt
  vgrid-value   = 1*unreserved-nt

  unreserved-nt = ALPHA / DIGIT / "-" / "_" / "."
  ALPHA         = %x41-5A / %x61-7A                         ; A-Z / a-z
  DIGIT         = %x30-39                                   ; 0-9

The format-term defines the global resource identifier schema as well as often some (or all) characteristics of the resource.

format-term and vgrid-value are subsets of verb-type and vvalue; VGRID restricts the grammar of these to unreserved-nt as specified in the URI specification).

Note: when using base64 encoded values as VGRID vvalue, use the url-and-filename-readybase64url characters.

The VRID can be directly used as the NSS part of an 'urn:valos:' prefixed URI.

Each valospace resource is identified by a VRID.

If a resource VRID has only VGRID part but no verbs the resource is called a global resource.

If a resource VRID has verbs then the verbs describe a fixed path from the global resource of its initial VGRID part to the resource itself. The resource is called a *fixed sub-resource* of that global resource.

Each resource is affiliated with an event log of its global resource.

All direct VRID context-terms are references to this event log JSON-LD context.

§ VRID is affiliated with an event log

The resource identified by a VRID is always affiliated with an event log of its global resource. Because the VRID doesn't contain the locator information of this event log it must be discoverable from the context where the VRID is used.

All context-terms of the VGRID and VRID vparams are references to the event log JSON-LD context (Note: this applies only to immediate but not to nested vparams).

Global resources can be transferred between event logs. To maintain immutability across these transfers VGRID's must not contain chronicle or other non-identifying locator information. Similar to URN's VRID's always relies external structures and systems for carrying locator information.

Note: uuid v4 (format term `~u4`) is recommended for now, but eventually VGRID generation will be tied to the deterministic event id chain (format term `~cc`). This in turn should be seeded by some ValOS authority.

Two VRIDs refer to the same resource iff their URN representations are urn-equivalent(i.e. if the two VRIDs are equivalent after section 3.1. case normalization for step 3. percent-encoding case normalization).

Maintaining the consistency between this lexical equivalence and the semantic equivalence of a resource which has been transferred between event logs without having to dereference VRIDs is useful but has implications.

Rule: When resources are transferred between event logs the semantics of their context terms and body-parts must remain equivalent.

A *simple equivalence* is that two simple prefix term definitions resolve to the same URI. An *extended equivalence* is when two extended term definitions in the source and target event logs are equivalent after normalization. These two equivalences are [will be] defined by this document.

More complex equivalences are outside the scope of this document but can be defined by specifications specifying segment types. These equivalences might take details of the particular verb-type into account and/or specify context definition additions which do not change the equivalence semantics.

§ VRID verbs identify fixed sub-resources - fixed ownership, inferred state, 'secondary keys'

In VRID context the vsteps-tail that follows the VGRID specifies a fixed path from the global resource to a *fixed sub-resource* of the global resource. The triple constraints of each verb in that path are _inferred as triples_ for the particular resource that that verb affects.

Principle: a fixed sub-resource using a particular vsteps-tail in its identifying VRID will always infer the triples that are required to satisfy the same vsteps-tail in a query context which starts from the same global resource.

This fixed triple inference is the meat and bones of the fixed sub-resources: they allow for protected, constrained semantics to be expressed in the valospace resources. This allows both simplified semantics (eg. properties _cannot_ be renamed so the complex functionality doesn't need to be supported on fabric level), more principled mechanism for chronicle crypto behaviours (permission relations are fixed sub-resources which simplifies security analysis but retains valospace convenience) and also a mechanism for expressing non-trivial resources such as hypertwin resources.

The sub-resources can be nested and form a tree with the global resource as the root. Typical verb sub-segments specify the edges in this tree (some verbs only specify the current node resource further without specifying a new edge). The global resource is the host resource for the first verb; the sub-resource of that segment is the host resource of the second verb and so on.

As the VRID identities of the sub-resources are structurally fixed to this tree the coupling between host and sub-resource must be static. The typical implementation for this is an ownership coupling.

§ List of VGRID formats:

VGRID context-term specifies the particular identifier format and possible semantics of the identified global resource. ValOS kernel reserves all context-terms matching '"i" 2( ALPHA / DIGIT )' for itself with currently defined formats exhaustively listed here.

§ VGRID format "`~u4`": UUID v4 of a native, insecure resource

An identifier for native valospace resource with an event log. This is insecure as there are no guarantees against resource id collisions by malicious event logs. These identifiers can thus only be used in trusted, protected environments.

§ VGRID format "`~bvo`": The content hash of Binary ValOS object

An identifier of an immutable octet-stream, with the content hash in the vvalue.

§ VGRID format "`~plt`": The id of an immutable Platonic resource With inferences

An identifier of an immutable, procedurally generated resource with its content inferred from the VPlot embedded in the vvalue. While of limited use in itself this is useful when used as the prototype of fixed ghost sub-resources which are quite mutable.

§ VGRID format "`~cih`": The id of a command-id hash-based insecure resource

An identifier which has been hashed from a command id, chronicle URI and a running counter.

§ VGRID format "`~chr`": The id of a command hash-based chronicle

A chronicle identifier which has been hashed from a command id and an authority URI.

§ VGRID format "`~ch3`": The id of Crypto-Hash-CHained secure CHronicle resource

An identifier of a native, secure valospace resource with an event log. This id is deterministically derived from the most recent hash-chain event log entry of the particular event which created it, the cryptographic secret of the creating identity and a salt, thus ensuring collision resistance and a mechanism for creator to prove their claim to the resource.

§ VGRID format "`~aur`": The id of an authority root resource

The fixed identifier of an immovable root resource of an authority chronicle. The authority VGRID param equals to the authority URI.

§ VGRID format "`~gh`": The derived Hash id of a native, insecure Ghost resource

This is a legacy format for native ghost resources, with id created from the hash of the 'ghost path' of the resource.

§ VGRID format "`~raw`": The insecure raw text id of a resource

An id with an unknown schema.

§ List of VRID-specific verb type semantics:

VRID *verb-type* specifies the relationship category between the segment host resource and sub-resource, a set of inferred triples as well as other possible constraints.

§ Shared example data
The examples below all share the following triples:
<urn:valos:$~u4.f00b> a valos:Entity ; V:specializationOf <urn:valos:$~u4.f00b-b507-0763>

§ verb type "`_`": fixed subspace sub-resource

Ghost sub-resources are products of ghost instantiation. All the ghosts of the directly _and indirectly_ owned resources of the instance prototype are flattened as _direct_ fixed sub-resources of the instance itself. The instance is called *ghost host* of all such ghosts.

§ Fixed ghost triple inference
`<urn:valos:$~u4.f00b@_$~u4.ba54>` reads as "inside the instance resource `f00b` the ghost of the $~u4 resource `ba54`" and infers triples:
<urn:valos:$~u4.f00b@_$~u4.ba54> V:ghostHost <urn:valos:$~u4.f00b> ; V:ghostOf <urn:valos:$~u4.ba54>

In case of deeper instantiation chains the outermost ghost segment provides inferences recursively to all of its sub-resources; nested ghost segments wont provide any further inferences.

§ Recursive ghost triple inference
`<urn:valos:$~u4.f00b@_$~u4.ba54@_$~u4.b7e4>` reads as "inside the instance resource `f00b` the ghost of `<urn:valos:$~u4.ba54@_$~u4.b7e4>`" and infers triples:
<urn:valos:$~u4.f00b@_$~u4.ba54@_$~u4.b7e4> V:ghostHost <urn:valos:$~u4.f00b> ; V:ghostOf <urn:valos:$~u4.ba54@_$~u4.b7e4>

§ verb type "`_`": fixed subspace override

Selects a variant resource value for a base resource within a fixed subspace. The variant resource provides inferred `subspacePrototype` fallbacks to an *inner* subspace and eventually to the non-variant base resource as well as to the homologous sub-resource of the host resource hasPrototype.

This means that no matter where a subspace variant is defined in the prototype chain or in the nested sub-structure its value will be found.

§ Fixed subspace triple inference
`<urn:valos:$~u4.f00b@.$.myProp@_$lang.fi>` is a lang fi variant of f00b myProp and infers triples:
<urn:valos:$~u4.f00b@.$.myProp@_$lang.fi> a V:ScopeProperty ; V:subspacePrototype <urn:valos:$~u4.f00b@.$.myProp> , <urn:valos:$~u4.f00b-b507-0763@.$.myProp@_$lang.fi> ; V:language "fi"

Subspace selectors can be used to access language variants, statically identified ghost variants within an instance, statically identified Relation's etc.

The verb segment-term can also specify triple inferences for *all* sub-resources in the subspace (not just for the immediate sub-resource of the selector segment).

§ Fixed subspace recursive inference

`<urn:valos:$~u4.f00b@_$~u4.b453@_$lang.fi@_$~u4.b74e@.$.myProp>` infers triples:


  <urn:valos:$~u4.f00b@_$~u4.b453@_$lang.fi@_$~u4.b74e@.$.myProp> a V:ScopeProperty
      ; V:ghostHost <urn:valos:$~u4.f00b>
      ; V:ghostOf <urn:valos:$~u4.b453@_$lang.fi@_$~u4.b74e@.$.myProp>
      ; V:subspacePrototype <urn:valos:$~u4.f00b@_$~u4.b453@_$~u4.b74e@_$lang.fi@.$.myProp>
      ; V:language "fi"

§ verb type "`.`": fixed ScopeProperty

Fixed properties infer a type, fixed owner and name.

§ Fixed scope property triple inference
`<urn:valos:$~u4.f00b@.$.myProp>` is a resource with fixed name "myProp", dominant type ScopeProperty, $~u4 resource f00b as the owning scope and a structurally homologous prototype inside f00b-b507-0763 and thus infers triples:
<urn:valos:$~u4.f00b@.$.myProp> a V:ScopeProperty ; V:scope <urn:valos:$~u4.f00b> ; V:hasPrototype <urn:valos:$~u4.f00b-b507-0763@.$.myProp> ; V:name "myProp"

The verbs `.O.`, `.O*`, and `.O~` denote the properties `V:value`, `V:id`, and `V:content'` respectively. These are the primary rdf:object sub-properties of ScopeProperty, Entity and Media, respectively (the 'O' in the verbs stands for rdf:object). When given as a parameter to a primary resource they modify it with a fixed rdf:object triple. In addition `.S-` and `.O-` denote `V:source` `V:target` which are the rdf:subject and rdf:object properties of a Relation.

§ Fixed rdf:object triple inference
`<urn:valos:$~u4.f00b@-out--$.PERMISSIONS:@.O-$~ih.8766>` is a PERMISSIONS relation with fixed ~ih target 8766 and infers triples:
<urn:valos:$~u4.f00b@-out--$.PERMISSIONS:@.O-$~ih.8766> a V:Relation ; V:ownerSource <urn:valos:$~u4.f00b> ; V:specializationOf <urn:valos:$~u4.f00b-b507-0763@-out--$.PERMISSIONS:@.O-$~ih.8766> ; V:name "PERMISSIONS" ; V:target <urn:valos:$~u4.8766>
Mnemonic: these verbs are read right-to-left, eg. `.O-` -> 'Relation rdf:object property is V:target'

§ verb type "`-`": fixed Relation

Fixed relations infer a type, fixed owner (connector), name and possibly source and target.

§ Fixed relation triple inference
`<urn:valos:$~u4.f00b@-out--$.PERMISSIONS@_$.1>` is a resource with fixed name "PERMISSIONS", dominant type Relation, ~u4 f00b as the source, a structurally homologous prototype inside f00b-b507-0763 and thus infers triples:
<urn:valos:$~u4.f00b@-out--$.PERMISSIONS> a V:Relation ; V:ownerSource <urn:valos:$~u4.f00b> ; V:hasPrototype <urn:valos:$~u4.f00b-b507-0763@-out--$.PERMISSIONS> ; V:name "PERMISSIONS" <urn:valos:$~u4.f00b@-out--$.PERMISSIONS@_$.1> a V:Relation ; V:subspacePrototype <urn:valos:$~u4.f00b@-out--$.PERMISSIONS> , <urn:valos:$~u4.f00b-b507-0763@-out--$.PERMISSIONS@_$.1>

§ verb type "`*`": fixed Entity

Fixed entities infer a type, fixed owner (parent) and name.

§ Fixed Entity triple inference
`<urn:valos:$~u4.f00b@*$.Scripts>` has a fixed name "scripts", dominant type Entity, $~u4 resource f00b as the owning container and a structurally homologous prototype inside f00b-b507-0763 and thus infers triples:
<urn:valos:$~u4.f00b@*$.Scripts> a V:Entity ; V:parent <urn:valos:$~u4.f00b> ; V:hasPrototype <urn:valos:$~u4.f00b-b507-0763@*$.Scripts> ; V:name "scripts"

§ verb type "`~`": fixed Media

Fixed medias infer a type, fixed owner (folder) and name.

§ Fixed Media triple inference
`<urn:valos:$~u4.f00b@~$.foo.vs>` has a fixed name "foo.vs", dominant type Media, $~u4 resource f00b as the owning folder and a structurally homologous prototype inside f00b-b507-0763 and thus infers triples:
<urn:valos:$~u4.f00b@~$.foo.vs> a V:Media ; V:folder <urn:valos:$~u4.f00b> ; V:hasPrototype <urn:valos:$~u4.f00b-b507-0763@~$.foo.vs> ; V:name "foo.vs"

§ Collected VPlot ABNF grammar

The VPlot grammar is an LL(1) grammar. The recursion is by virtue of vparam productions which can nest VPlots themselves without additional encoding.

The list of definitive rules:

  vplot       = 1*( "(" vstep ")" )
  vstep       = vparam *( "'" vparam )
  vparam      = vplot / [ vterm ] [ "!" ( vvalue / "!" vdata ) ]

  route-vplot = vstep *( "/" vstep )
  urn-vplot   = vstep *( ":" vstep )

  vterm       = 1*unencoded
  vvalue      = 1*unencoded
  vdata       = 1*b64urlchar

  unencoded   = b64urlchar / "." / "~" / "*"
  b64urlchar  = ALPHANUM / "-" / "_"

  ALPHANUM    = %x30-39 / %x41-5A / %x61-7A                             ; 0-9 / A-Z / a-z

In addition there are pseudo-rules which are not used by an LL(1) parser but which have well-defined meaning and can thus be referred to from other documents.

The list of informative pseudo-rules:

  vverb           = verb-type *vparam
  vcontext-param  = "$" context-term "." vvalue

  vrid            = "@" "$" vgrid "@" *(vstep "@") "@"
  vgrid           = format-term "." vgrid-value *vparam
  format-term     = "~" 1*(ALPHA / DIGIT / "_")
  vgrid-value     = 1*( unencoded / pct-encoded )

  context-term-ns = ALPHA 0*30unreserved-nt ( ALPHA / DIGIT )

There are couple notes not explicitly expressed by the the grammar itself. These notes primarily relate to LL(1)-parseability:

Pseudo-rule 'vrid': this class contains all 'vplot' productions with 'vgrid' as their first expansion.
Pseudo-rule 'context-term-ns': this class contains all 'context-term' expansions which match this more restrictive specification (max 32 chars, special chars only in the middle). All 'context-term's which are plain namespace prefixes should be restricted to this rule as this is the prefix grammar of some relevant prefix context.
Editorial Note: which context was this again? Neither SPARQL, Turtle nor JSON-LD have this limitation.
The nesting hierarchy can be manually quickly established by first splitting a valid VPlot string by the delimiter regex /(@$.)/ (retaining these delimiters in the result). Then a tree structure is formed by traversing the array from left to right and dividing it to different nesting depths. The nesting depth is increased for the initial "@" and for each "@" that is preceded by a "." (corresponds to the 'vplot' production prefix of some 'short-param' production) and reducing the nesting depth for each "@" that is succeeded by a "$", "@" or EOF (corresponds to the terminator of the last 'vgrid' or 'verb' production of some 'vplot' production). All remaining "@" correspond to non-final 'vgrid' or 'verb' production terminators of some 'vplot' rule production and thus don't change the nesting depth.

§ VPlot design considerations and case studies

This section contains considerations on the choice of character set and on where and how VPlots need or don't need to be encoded. There's a historical emphasis on the decision of which characters to use as delimiters (ie. "@", and "$").

§ VPlot composition and decomposition should be robust

§ No contextual delimiters

If a character is a delimiter in some context within a VPlot then this character must always encoded when not used as a delimiter.

§ All value segments are encoded and decoded using encodeURIComponent

Characters not encoded are ruled out from structural delimiters. This leaves "?" | "#" and "/" | ":" | "@" and "$" | "+" | ";" | "," | "=" | "&"

§ Contexts where VPlot doesn't need encoding

In general VPlots don't require encoding in contexts where the VPlot delimiters "@" / "$" and the encodeURIComponent result character set ALPHA / DIGIT / "-" / "_" / "." / "~" / "!" / "*" / "'" / "(" / ")" can be used.

Editorial Note: "(" and ")" can in principle be substantially inconvenient in many contexts. But as they're grouped with "!" / "*" / "'" which have their uses in verb-type's all five are for now retained as allowed characters.

§ As RFC 3986 URI segment-nz component

VPlots can be used as-is in URI path parts (except as segment-nz-nc, see below). This rules out "?", "#", "/" from structural delimiters

§ As a typical sequence entry

Rules out "," | ";" from structural delimiters

§ As part of RFC 3986 URI query component when consumer is known not to decode

VPlot can and is intended to be used as-is in the query part (even as the right-hand side value of "=") as long as the URI consumer or possible middlewares don't perform x-www-form-urlencoded (or other) decoding of the key-value pairsbefore VPlot expansion.

Rules out "=" , "&" from structural characters.

Note: This is completely regular. If the consumer is known to explicitly decode query values and because VPlots can contain "%" characters they must be appropriately symmetrically encoded. This can result in double encoding. However as the intent is that VPlot expansion should be considered to be part of the URI parsing and separation itself any separate encoding and decoding should not be needed.

§ As RFC 3986 URI fragment component

Doesn't rule out any delimiter options not yet ruled out.

§ As RFC 8141 URN NSS components

Doesn't rule out any delimiter options not yet ruled out. Specifically this does not rule out ":" as that is allowed in NSS sub-parts.

§ As RFC 8141 URN rq-, and f-component

Covered by URI query and fragment sections.

§ VPlot must be used escaped/quoted/encoded in following contexts

§ In HTTP/1.1 headers always as a quoted-string

URI's in general need to be quoted here and VPlot is URI-like. This retains "@" as an allowed delimiter.

§ In URI relative-part with no scheme must be prefixed with "./"

This retains ":" as an allowed delimiter which segment-nz-nc would otherwise prevent.

§ In form fields as x-www-form-urlencoded

Encoded and serialized as per https://url.spec.whatwg.org/#urlencoded-serializing

§ The tilde problem with URN RFC 2141 is solved by RFC 8141

RFC 2141 reserves "~" but encodeURIComponent doesn't encode it. To maintain direct drop-in 2141 compatibility would require disallowing "~" from the character set. This in turn would complicate specific javascript domain implementations as they would have to encode "~" separately without being able to solely rely on encodeURIComponent.

As this concern is not likely to be a problem in practice anyway we choose to refer to RFC 8141 for URN's which removes "~" from the set of reserved character. This solves this (relatively theoretical) issue.

§ The VPlot fabric namespace of the library ontology of @valos/plot

The vocabulary for defining the hierarchical ValOS identifiers and for extending them with new step semantics

§ @valos/plot IRI prefixes

Prefix	IRI
rdf	http://www.w3.org/1999/02/22-rdf-syntax-ns#
rdfs	http://www.w3.org/2000/01/rdf-schema#
xsd	http://www.w3.org/2001/XMLSchema#
owl	http://www.w3.org/2002/07/owl#
dc	http://purl.org/dc/elements/1.1/
VPlot	https://valospace.org/plot/0#
VKernel	https://valospace.org/kernel/0#
VState	https://valospace.org/state/0#
VLog	https://valospace.org/log/0#
VValk	https://valospace.org/valk/0#

§ VPlot fabric classes The class of classes which are defined by the ValOS kernel domain ontologies.

This section describes fabric classes introduced by the 'VPlot' namespace

rdfs:subClassOf	description
*#VPlotLiteral*
rdfs:Literal rdfs:List	The class of all literals which can be represented as some VPlot rule or pseudo-rule. If this class is used as literal datatype URI the literal contains the flat string VPlot rule representation. Otherwise when this class is the range of a property which is used as a predicate in a triple, and the object of the triple is not a literal, then the object contains the segmented representation of the VPlot rule value as an rdf List.
*#VPlot*
VPlot:VPlotLiteral	The class of all resources that can be represented by the VPlot rule 'vplot' (the string representation always begins with '@')
*#VRID*
VPlot:VPlotLiteral	The class of all resources that can be represented by the VPlot pseudo-rule 'vrid', ie. which have have a 'vgrid' as their first step (the string representation always begins with '@')
*#Verbs*
VPlot:VPlotLiteral	The class of all resources that can be represented by the VPlot pseudo-rule 'verbs', ie. which represent a path between resources ie. which don't have a 'vgrid' as their first step (the string representation always begins with '@').
*#Verb*
VPlot:VPlotLiteral	The class of all verb names. A context that performs VPlot valks shall provide the conforming implementations for the subset of verbs that it has declared to support.
*#VGRID*
VPlot:VPlotLiteral	The class of all resources representing the VPlot rule 'vgrid' (always begins with '$').
*#VParam*
VPlot:VPlotLiteral	The class of all resources representing the VPlot pseudo-rule 'vparam' (always begins with '$' or ':').

§ VPlot fabric properties The class of properties which are defined by the ValOS kernel domain ontologies.

This section describes fabric properties introduced by the 'VPlot' namespace

rdfs:domain	rdfs:range

§ VPlot fabric methods The class of all valosheath type prototype methods.

This section describes fabric methods introduced by the 'VPlot' namespace

rdfs:domain	rdfs:range

§ VPlot fabric globals The class of all valosheath global resources.

This section describes fabric global objects introduced by the 'VPlot' namespace

rdf:type	Comment

§ VPlot remaining vocabulary terms

rdf:type	rdfs:subClassOf