Musings on document entities and IRI resolution

[uogbuji]

Putting some serious consideration into how we conceptualize and handle document entities, and the IRI resolution conventions. Right now @docheader/@document is really just used to assert a node for the document itself. @docheader/@base is too generic a name, and should at a minimum be renamed @nodebase, used to resolve relative node ID IRIs.

I think @document should be used for Node ID resolution if @nodebase is not specified. Philosophically, the document serves as a container for the nodes it defines, though this is complicated by the case of documents with partial or supplementary node definitions. I also like the idea of having an optional flag for the parser where each assertion can have a sub-property @source which is the source document IRI. This is a useful provenance support, but should be optional, since we'd want to avoid graph bloat where it's not needed.

This ties into my thinking that onya.serial.literate_lex.parse should actually be a method on a parser class which can contain flags such as document_source_assertions.

Classic RDF had a convention where a document could contain the definitions of entities, and thus a namespace such as https://www.w3.org/1999/02/22-rdf-syntax-ns#, ending with a hash so that terms such as rdf:type were conceptually a type entity defined within that document abstraction, using the HTML fragment ID convention. This approach was already discarded by the time the RDF Schema spec came around, in favor of base URIs ending with /, but I think it's still a useful construct. It also ties into the idea, taken into Onya, that IRI resolution is a lexical operation rather than one in the proper RFC 3987 sense—it's just a concatenation of the base IRI with the relative. This of course suggests that most base IRIs should end in # or / to conform to well-established conventions.