Skip to content

Latest commit

 

History

History
100 lines (72 loc) · 3.11 KB

sep-0018.md

File metadata and controls

100 lines (72 loc) · 3.11 KB
Raw

Preamble

SEP: 0018
Title: Data Entry Namespaces
Author: MisterTicot (@misterticot), Leigh McCulloch (@leighmcculloch)
Status: Active
Created: 2018-10-26
Updated: 2020-06-30
Version: 0.3.0

Simple Summary

Defines a standard syntax to represent namespaces in data entries.

Abstract

This SEP provides a standard way to represent namespaces into Stellar accounts data entries.

Motivation

As a generic mechanism to store key/value pairs on the ledger, data entries accept a very wide range of use cases. If each actor uses it following its syntax, it will lead to a confusing experience and ultimately to name conflicts.

Introducing namespaces allow to hierarchize and organize data.

This SEP provides guidelines for other SEPs, external applications as well as libraries or utilities dealing with data entries.

Specification

Namespace hierarchy is encoded in the key using one or more terms separated by dots. Terms are made of lowercase letters, underscore and numbers and mustn't start with a number.

Examples

app.example_org.id
config.memo_required
config.multisig.coordinator
  • Term REGEXP: [_a-z][_a-z0-9]*
  • Key REGEXP: [_a-z][_a-z0-9]*(\.[_a-z][_a-z0-9]*)*

Namespace Registry

To guarantee interoperability and avoid naming conflicts, app-specific data must live under their reserved namespace:

  • app: Namespace available to app-specific keys. Keys must be defined under app.{domain}, with dot(s) replaced by underscores. For example, "example.org" defines its keys under app.example_org.

Other namespaces have special meaning according to their SEP documents. When a SEP makes use of account data entries, it must be listed here and referenced:

  • config: Namespace available for use by ecosystem-wide configuration:
    • config.memo_required: SEP29
    • config.multisig: SEP19

Rationale

Syntax

The namespace syntax had to be familiar, and terms have to be written in a way that is valid across a broad range of programming languages.

Parsing the data tree must lead to the same namespace/key/value structure regardless of the programming language being used. This is the reason why term syntax must be restricted, as unusual characters could lead to difficulties or errors. The lowercase restriction is meant to prevent a different data tree interpretation between case-sensitive and case-insensitive languages.

Identifier/namespace conflict

Conflict occurs when a term is used both as an identifier and a namespace. If for example a data entry with key app.example_org.language exists, and a data entry with key app.example_org.language.region exists, an application parsing the data entries into internal types or data structure will struggle to reconcile how to store the value assigned to app.example_org.language.

app.example_org.language = en
app.example_org.language.region = US

Applications should avoid defining namespaces that are also identifiers by ensuring namespaces are not given values. Example:

app.example_org.language.language = en
app.example_org.language.region = US