Before you read this document, make sure that you understand the main ideas of Local Names.
This document is the Local Names Namespace Description Specification, version 1.2. It is abbreviated "LNNDS v1.2". This document obsoletes prior LNNDS.
This specification is maintained by Lion Kimbro, who is available by e-mail at lion@speakeasy.org.
Major changes, releases, and news updates are posted to the Local Names website news page, and accompanying RSS feed. Posts are made roughly once every 6-12 months.
Ongoing development is presently (2005-06-16) coordinated on Lion Kimbro's blog, which has an RSS 2.0 news feed. Relevant posts are made roughly once every 3-9 months.
Additional contact methods:
The project presently keeps no mailing lists. Either write on Lion Kimbro's blog, write on CommunityWiki, call Lion's cell phone, or otherwise get in contact with Lion Kimbro or a member of the One Big Soup effort.
Lion Kimbro's contact information is on his web site.
"One Big Soup" was the name of the super-project that gave rise to Local Names. The goal of One Big Soup was to develop Internet public communication systems by tying together existing Internet technologies with new protocols. Read CommunityWiki:OneBigSoup and A Manifesto for Collaborative Tools for more information.
Local Names namespace descriptions are encoded with:
Content-type: text/plain; charset=UTF-8
Apache 2.0 can serve text files with these settings with the following directive:
AddType "text/plain; charset=UTF-8" txt
Syntax
<namespace_description> ::= { <line> }
<line> ::= <newline> |
<comment> <newline> |
<record> <newline>
<comment> ::= "#" { <comment-character> }
<record> ::= <record_type> <one_space> <column> <one_space> <column>
<column> ::= "." |
<quotation-mark> { <column-character> } <quotation-mark>
<record_type> ::= "." |
"LN" |
"NS" |
"X" |
"PATTERN"
<one_space> : ASCII space (32)
<quotation-mark> : ASCII quotation mark (34,) like so: "
<newline> : ASCII NL, CR, FF
<comment-character> : any UTF-8 character, save NL, CR, FF
<column-character> : any UTF-8 character, escaping the following:
Newline: \n
Quote: \"
Slash: \\
A slash followed by anything else
SHOULD generate an error.
| <blah-blah> | non-terminal symbol |
| "blah-blah" | literal text, as ASCII, without quotes around it |
| { blah blah } | repetition, zero or more "blah blahs" |
Accept 0D, 0A, or 0D0A as line breaks.
Lines are one of the following three forms: Blank, comment, or record.
Blank lines are lines consisting of nothing but white space.
Comment lines start with a hash (#).
Records are composed of three columns.
The first column is the record type, and the meaning of the remaining two columns depends on the first column.
The first columnm, the record type, can read either "LN," "NS," "X," or "PATTERN." (No quotation marks, no commas, no periods. The first column can also be just a period. A period means a repetition of the previously used record type.
The second and third columns can be:
That is, you can use a period in any column.
Periods never have quotation marks around them. If you are in the first column, you never use quotation marks. Quotation marks are found around the second or third column if you aren't using a period.
NOTE: In previous versions of the spec, you could opt to not have quotes around the second and third columns. No longer. Nobody ever used it, save for X records.
This concludes the description of the syntax.
This means to bind the name to the URI.
This means to link the namespace to a target namespace (described at the URI.) The target namespace is referred to by a convenient name, the "link key."
This means to create a link to a URI template.
The URI template is referred to by a convenient name, the "pattern key."
Replacements in the URI template are made by identifiers: "$NAME" and "$ARGn" where n is a number, starting from 1. "$NAME" is equivalent to "$ARG1".
Resolution of the pattern depends upon the query style (see the Local Names XML-RPC Query Interface for details,) but basically, if a pattern is named in the query path, then the remainder of the path is interpreted as pattern arguments, and the final URI is created from that.
Examples:
Query path: foo, bar Pattern record: PATTERN "foo" "http://foo/$NAME" Result: "http://foo/bar"
Query path: foo, bar, baz Pattern record: PATTERN "foo" "http://foo/$ARG1/$ARG2" Result: http://foo/bar/baz
This means to set some extension data for the immediate namespace.
A namespace description interpreter should accept any key-value pair given in X records.
These are standard X records, recommended by this spec for use. Everything is optional, but X "VERSION" is strongly recommended.
Text like this is an example.
As is. Exactly as seen above. Exactly.
The description's author's name.
X "AUTHOR" "Lion Kimbro"
A link to the description's author's FOAF file.
X "AUTHOR-FOAF" "http://www.speakeasy.org/~lion/foaf.rdf"
The date the namespace description was last changed.
X "LAST-MODIFIED" "2005-01-28"
A preferred short name for the namespace. Useful if you are automatically generating an NS record, given just a URL of a namespace description.
X "PREFERRED-NAME" "The Prophet, by Gibran"
The URL of a Local Names Query Server that usually keeps this namespace description (and perhaps it's neighbors) cached.
X "PREFERRED-QUERY-SERVER" "http://example.net/lnquery/"
These three X records tell how to edit the namespace via the Local Names XML-RPC Store Interface.
All, some, or none of these 3 X records can be defined.
AUTHORITATIVE-STORE-SERVER tells the URL of the store interface.
AUTHORITATIVE-STORE-NAMESPACES tells the name of the namespace, as understood by the store interface.
AUTHORITATIVE-STORE-PASSWORD tells the password to use when editing the namespace via the store interface. Remember, you don't have to list this.
If a namespace or password are not given, an interpreter will likely default to default namespace "default" and null password "password", as described in the specification.
X "AUTHORITATIVE-STORE-SERVER" "http://example.net/lnquery/"
X "AUTHORITATIVE-STORE-NAMESPACE" "robotics"
X "AUTHORITATIVE-STORE-PASSWORD" "xyzzy"
(Notes below.)
X "FINAL" "The Prophet, by Gibran"
This standard requires the special treatment of X "FINAL".
If a name is looked up, and no LN entry is found for the name, but there is an X "FINAL" (URI pattern) entry found, then the name is fitted to the pattern, and that is the final URI.
The pattern can include the text "$NAME". Wherever "$NAME" appears in the pattern, "$NAME" is replaced with the name that is being fit to the pattern.
Examples:
Name: bar Pattern: http://foo/$NAME Result: http://foo/bar
Name: bar Pattern: http://foo/$NAME$NAME--$NAME Result: http://foo/barbar--bar
A Local Names resolver MUST correctly handle and interpret "X FINAL."
Wherever you can put a URL,] you can also put a relative URL. The URL is specified relative to the last URL path element leading to the namespace description itself.
Q. Can LN, NS, and PATTERN records share the same name?
A. An LN record can reuse a name also used by an NS or PATTERN record. But NS and PATTERN records cannot share names with each other.
This is because an LN record is used for looking up individual names, but both PATTERN and NS records are used for looking up namespaces.
Recall that a PATTERN simulates a namespace, so the name of a PATTERN will collide with the name of an NS.
Q. What happens if there is an LN redefinition, or an NS/PATTERN redefinition?
A. Use the first value given. Log an error.
Q. How do X "AUTHOR" and X "AUTHOR-FOAF" relate?
A. AUTHOR is used to name authors. AUTHOR-FOAF is used to link to author FOAF descriptions. They do not refer to one another. If you want to list three authors by name, and link to three other authors by FOAF, or perhaps one of the authors that is explicitely named also has a FOAF link- it does not matter, and there is no specification about how they relate. The interpreter cannot know, save if it notices that the FOAF description features says that a person's name is the same as an AUTHOR field says.
Try not to overthink this one. If all you have are names of authors, just list the names of authors. If all you have are FOAF links, include the FOAF links. If you like, list both names and FOAF links.
Q. What happens if an X record is redefined?
A. X records are a special case; X records line up into a list. The first entry to appear in the text file is the first entry to appear in the list.
This is so that meta-data requiring lists can exist. (Albeit somewhat clumbsy.)
In particular, X "PREFERRED-NAME" could be used repeatedly to list multiple possibilities, in case a preferred name is already taken.
X "AUTHOR" may be used to name multiple authors.
But something like X "VERSION" should never be repeated. It is syntactically okay, but it shouldn't be done.
The same goes for "DATE-CHANGED."
If you wish to advertise a namespace from a web page, place the following in the head of your HTML document:
<link rel="meta" type="text/plain" title="localnamespace" href="..." />
example:
<link rel="meta" type="text/plain" title="localnamespace" href="http://ln.taoriver.net/localnames.txt" />