O GEUL aponta documentos por ID (Issuer, ID do documento, ID da versão), e não por URL em texto. O endereço é determinado pelo ID. Esta página define as regras de publicação de que codificadores, decodificadores e resolvedores precisam para funcionar em conjunto. Os níveis de Issuer e as formas de publicação são definidos em Issuer e publicação.

Notação de ID

Os IDs usados em endereços são escritos em hexadecimal.

  • O prefixo é 0x em minúsculas. O hexadecimal usa A-F em maiúsculas. O resolvedor também procura um endereço escrito em minúsculas convertendo-o para maiúsculas.
  • O número de dígitos é fixo em largura × 4. Os zeros à esquerda não são omitidos, e o número de dígitos é a própria largura.
  • Ao escrever um endereço, o Issuer é escrito com o número de dígitos da largura de emissão: 2 WORD 8 dígitos, 4 WORD 16 dígitos, 16 WORD 64 dígitos.
  • Ao ler, o Issuer é aceito com 8, 16 ou 64 dígitos. A notação mais longa de um Issuer ID curto, com zeros à esquerda, é procurada como o mesmo Issuer (0x00000001 e 0x0000000000000001 são o mesmo Issuer, Issuer e publicação).
ObjetoLarguraDígitosExemplo
Issuer2 WORD80x00000001
Issuer4 WORD160x0000000100000000
Issuer16 WORD640x + 64 dígitos
Codec ID2 WORD80x00000AA0
ID do documento4 WORD160x0000000000000000
ID da versão2 WORD80x00000003
Hash de conteúdo16 WORD640x + 64 dígitos
  • O Codec ID de um código direto do GEUL é o seu TAG WORD (L=0) escrito como valor de 32 bits (TRIPLE 0x0AAL → 0x00000AA0). O Kind está contido no TAG, portanto não há colisão.
  • Os Codecs de formato ISSUER de outros Issuers ficam sob o codecs/ desse Issuer, com o número de Codec do registro. Exemplo: o CRC32C do IETF é 0x00000007/codecs/0x0000C000/.
  • O Codec ID de um Codec de Issuer é o número de Codec (2 WORD) do registro. O Issuer atribui os números de Codec de modo que não se repitam dentro do seu <Issuer>/codecs/, independentemente do Kind (Reference, Value, Edge). O endereço não se divide por Kind (não há pastas como references/, values/, edges/).
  • O resolvedor trata como erro o caso em que o Kind do registro difere do Kind do destino do DECLARE do seu documento de Codec.
  • A publicação rejeita subir um Codec diferente sob o mesmo Codec ID.
  • As regras do ID da versão (a partir de 1, 0 é a mais recente, atribuído pelo publicador, novo ID de documento ao esgotar) são definidas em documento.

Endereço de publicação

/.well-known/geul/issuers/latest.geul                              Lista de Issuers, mais recente
/.well-known/geul/issuers/<ID da versão>.geul                      Lista de Issuers, versão indicada
/.well-known/geul/issuers/versions.geul                            Lista de versões da lista de Issuers
/.well-known/geul/<Issuer>/codecs/<Codec ID>/latest.geul           Codec, mais recente
/.well-known/geul/<Issuer>/codecs/<Codec ID>/<ID da versão>.geul   Codec, versão indicada
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul         Lista de versões do Codec
/.well-known/geul/<Issuer>/docs/<ID do documento>/latest.geul      Documento, mais recente
/.well-known/geul/<Issuer>/docs/<ID do documento>/<ID da versão>.geul   Documento, versão indicada
/.well-known/geul/<Issuer>/docs/<ID do documento>/versions.geul    Lista de versões do documento
/.well-known/geul/<Issuer>/hashes/<hash de conteúdo>.geul          Consulta por hash de conteúdo

Exemplo: /.well-known/geul/0x00000002/docs/0x0000000000000000/latest.geul

  • O caminho segue o .well-known da RFC 8615. geul.org e as publicações privadas usam o mesmo caminho, mudando apenas o domínio. O único sufixo a registrar é geul.
  • A lista de Issuers é issuers/. Codecs, documentos comuns e hashes ficam sob a pasta do Issuer, em codecs/<Codec ID>/, docs/<ID do documento>/ e hashes/. A lista de Issuers também começa na versão 1 e tem versions.geul (documentos de lista).
  • latest.geul é uma palavra reservada e um alias. Não é armazenado. Procura-se a versão mais recente no versions.geul do mesmo lugar e entregam-se, como estão, os bytes dessa versão. Não há redirecionamento. É igual para todo latest.geul da lista de Issuers, de Codecs e de documentos.
  • O endereço canônico de uma versão é /<Issuer>/docs/<ID do documento>/<ID da versão>.geul. Para Codecs, é /<Issuer>/codecs/<Codec ID>/<ID da versão>.geul. Outros endereços que entregam o mesmo conteúdo apontam o endereço canônico por Link: rel=canonical.
  • O endereço com versão indicada e o endereço por hash de conteúdo são imutáveis. Endereços imutáveis podem ficar em cache permanente e em CDN. Quem recebe verifica pelo hash de conteúdo da lista de versões (ou do registro de bloqueio).
  • Para procurar por hash de conteúdo, é preciso conhecer o Issuer. Não há consulta global apenas pelo hash.
  • Documentos de Codec não têm ID de documento. Apontam a si mesmos e à versão por CODEC-POINTER (Issuer, Codec ID, ID da versão).
  • O ID sempre começa com 0x. Assim, os nomes reservados (issuers, codecs, docs, hashes, latest.geul, versions.geul) ou nomes dados por pessoas não colidem com IDs, mesmo que sejam palavras só de hexadecimal como add e cafe.
  • A localização (de qual servidor se recebe) não entra no conteúdo do documento. Se entrasse, o hash de conteúdo mudaria quando o endereço mudasse. A localização é determinada pela configuração de quem recebe o documento.

Forma de publicação e consulta

  • O endereço é um endereço lógico. O publicador pode entregar arquivos individuais ou pack; no caso de pack, não se pode receber diretamente pela URL do endereço, e lê-se com um resolvedor GEUL.
  • Quer esteja armazenado em arquivos individuais, em pack ou em pack zstd, encontra-se pelo mesmo endereço. Endereços fora dos 10 formatos acima e endereços inexistentes dão 404 (não encontrado).

Ferramenta de linha de comando geul (gogeul):

geul get <endereço>     emite o binário do documento GEUL puro na saída padrão
geul show <endereço>    mostra o documento em texto
  • geul get aceita endereços file:// e https://. Endereços fora dos 10 formatos e endereços inexistentes terminam em 404 (não encontrado).

O pkg/resolve da biblioteca Go gogeul tem uma função de consulta para cada endereço. Todas devolvem o binário GEUL puro ([]byte). Como o ID da versão começa em 1, Latest (0) é a mais recente. Um endereço inexistente é o erro de inexistência (ErrNotFound).

const Latest uint32 = 0

Issuers(ctx, v)               / IssuersVersions(ctx)
Codec(ctx, issuer, codec, v)  / CodecVersions(ctx, issuer, codec)
Doc(ctx, issuer, doc, v)      / DocVersions(ctx, issuer, doc)
Hash(ctx, issuer, hash)

ParseAddr(s string) (Addr, error)   // formatos fora dos 10: 404 (não encontrado)
Fetch(ctx, Addr) ([]byte, error)    // geul get = ParseAddr → Fetch → saída padrão

Especificação de formato

  • O endereço de publicação termina em .geul e é binário (application/vnd.geul).
  • A forma canônica do documento é o binário. O hash de conteúdo e a assinatura são calculados apenas sobre o binário.

Documentos de lista

O documento de lista é um só: a lista de Issuers issuers/. Liga Issuers a domínios (lista de Issuers). Começa na versão 1 e tem versions.geul. O ID de documento da lista é o ID de documento reservado 0xFFFFFFFFFFFFFFFF (Issuer geul.org 0x00000000). Todo Issuer reserva os IDs de documento 0x0000000000000000 e 0xFFFFFFFFFFFFFFFF (Issuer e publicação).

  • latest.geul é um alias não armazenado. Procura-se a versão mais recente em versions.geul e entregam-se os seus bytes.
  • PUBLICATION, DEPRECATION e TOMBSTONE em issuers/versions.geul apontam a versão da lista por DOC-POINTER (0x00000000, 0xFFFFFFFFFFFFFFFF, ID da versão). Assim, mesmo recebendo por hashes/, sabe-se de que é a lista (PUBLICATION).
  • O ID de documento 0xFFFFFFFFFFFFFFFF não é obtido em nenhum Issuer pelo endereço <Issuer>/docs/<ID do documento>/ (404). O outro ID de documento reservado, 0x0000000000000000, é o documento de índice de definição de termos daquele Issuer e fica sob docs/ (Issuer e publicação).
  • Os documentos de lista não têm DOC-ID. De que é a lista, diz o DOC-POINTER dos registros (DOC-ID).
  • Documentos e Codecs são encontrados diretamente pelo ID calculado a partir do registro, sem lista (nome de documento).

Nome de domínio

O nome de domínio não é um endereço URL de publicação. Um endereço que use um domínio na posição de <Issuer> ou um nome na posição de ID está fora dos 10 formatos acima e dá 404 (não encontrado). Também não há redirecionamento do nome para o endereço por ID.

  • O nome de domínio é entrada do resolvedor e da CLI. O resolvedor converte o domínio em Issuer ID pelo BIND da lista de Issuers issuers/. O ID convertido é registrado no registro de bloqueio. Não há endereço por nome de documento (nome de documento).
  • O endereço canônico, a chave de cache e o objeto da assinatura são o endereço por ID.
  • O domínio é escrito em minúsculas, e os domínios internacionalizados em forma IDNA (punycode). Não se acrescenta o . final.
  • Issuers de 16 WORD, que não têm registro, e ambientes isolados (air-gapped) sem acesso a geul.org não podem usar nomes de domínio. Usam o ID.

Lista de Issuers

A lista de Issuers é um documento sob /.well-known/geul/issuers/ (a mais recente é issuers/latest.geul). Liga Issuers a seus nomes (domínios).

BODY
  BIND   Subject = ISSUER-POINTER(Issuer)   nome = "geul.org"
  …
  • O Subject é ISSUER-POINTER (o próprio Issuer), e o nome é ligado por BIND.
  • O nome é um domínio que passou pela prova de propriedade. É escrito em minúsculas, e domínios internacionalizados em IDNA (punycode). Um nome liga-se a um único Issuer.
  • O nome de exibição do Issuer legível por pessoas (por idioma) é anexado ao mesmo Subject como LABEL de enunciado.
  • É assinada por geul.org (Issuer GEUL), e, quando muda, acrescenta-se e não se corrige (a mesma regra de cadeia da lista de versões).

Nome de documento

Não há endereço por nome de documento. Documentos e Codecs são encontrados por ID.

  • Não há índice que converta nomes de documentos ou de Codecs em ID. Também não se coloca na lista de versões o BIND do nome de documento (PUBLICATION).
  • O índice para navegação por pessoas é feito pela ferramenta (visualizador) a partir do inventário de pack.
  • O endereço canônico, a chave de cache e o objeto da assinatura são o endereço por ID. IMPORT e as citações dentro de documentos usam apenas ID.
  • O título legível por pessoas (por idioma) é anexado como LABEL de enunciado.

Documentos excluídos

  • O endereço de uma versão revogada por exclusão legal ou de ofício (TOMBSTONE) também dá 404 (não encontrado), como qualquer endereço inexistente.
  • Uma versão com recomendação de descontinuação (DEPRECATION) não dá 404. Continua sendo entregue por esse endereço de versão.
  • A exclusão fica na lista de versões como um registro TOMBSTONE (DOC-POINTER dessa versão, categoria do motivo).

Camadas

O GEUL expressa até a procedência, os metadados e as listas como documentos GEUL. O mínimo necessário para lê-los é embutido no decodificador, para romper a circularidade. Cada camada depende apenas das camadas inferiores.

CamadaConteúdoDepende de
Camada 0Regras embutidas no decodificador: enquadramento, hash de conteúdo, verificação de assinatura, Codecs de registros da lista de versões (PUBLICATION, DEPRECATION, TOMBSTONE), vocabulário de especificação de Codec (DECLARE, FIELD, ENUM, CODEC), marcadores de posição (0x0000, 0x0010, 0x0020), chaves de confiança recebidas de fora do documentoNada. Não consulta
Camada 1Documentos da lista de versõesCamada 0
Camada 2Documentos comuns, codebooks, documentos de especificação de Codec, documentos de chave de verificação de IssuerEncontrados pela camada 1 e verificados pela camada 0
  • Nenhuma camada depende de si mesma nem de camadas superiores.
  • Distingue-se o que se expressa em GEUL do que só se lê interpretando em GEUL. A camada 0 pode ser expressa em GEUL, mas sua interpretação não exige consulta.
  • O núcleo fixo que não pode ser convertido em documento TOULMIN, como o significado do julgamento, também fica aqui (TOULMIN).

Lista de versões

O publicador mantém, para cada documento, um documento de lista de versões, em que escreve em sequência (/<Issuer>/docs/<ID do documento>/versions.geul; para Codecs, /<Issuer>/codecs/<Codec ID>/versions.geul; para a lista de Issuers, issuers/versions.geul). O formato dos registros e a estrutura do documento são definidos em PUBLICATION.

DOC-*
  SPEC-VERSION
  PARENT          hash de conteúdo da lista de versões anterior
  RECORDED-AT     instante em que esta lista foi emitida
  NEXT-LOCAL-ID   próximo LOCAL ID a atribuir
  SIGNATURE       assinatura do publicador
BODY
  PUBLICATION     #1  documento@1  hash de conteúdo
  PUBLICATION     #2  documento@2  hash de conteúdo
  DEPRECATION     #3  documento@1
  …
END
EdgeSignificado
PUBLICATIONPublica uma versão do documento e seu hash de conteúdo
DEPRECATIONMarca uma versão publicada com recomendação de descontinuação. Continua sendo interpretada
TOMBSTONEExclui uma versão publicada (exclusão legal ou de ofício). Registra a categoria do motivo
  • Os registros só são acrescentados. Não se corrige, apaga ou reordena. Deprecar e excluir também acrescentam registros. A nova lista mantém na frente, como estava, o BODY da lista anterior e acrescenta registros, e as listas se ligam por uma cadeia de hashes de PARENT.
  • Significa que o registro de publicação não é corrigido, e é diferente da revisão do conteúdo do documento (documento). O estado atual de uma versão é calculado aplicando os registros em ordem.
  • O ID da versão é ascendente a partir de 1, sem lacunas. O mesmo conteúdo não é publicado de novo.
  • A versão mais recente é a mais alta que não é nem desaconselhada nem excluída.
  • Os registros não levam instante. O RECORDED-AT da primeira lista em que o registro apareceu é o instante de publicação.
  • A lista de versões não tem DOC-ID. O DOC-POINTER dos registros (ID do documento; para a lista de Issuers, o ID de documento reservado) diz de que é a lista.
  • A lista de versões não tem IMPORT e usa apenas Codecs da camada 0. O BODY contém apenas PUBLICATION, DEPRECATION e TOMBSTONE.
  • As listas de versões anteriores são apontadas apenas pelo hash de conteúdo (<Issuer>/hashes/<hash de conteúdo>.geul), e o histórico se liga pela cadeia de PARENT.
  • Os endereços mutáveis são latest.geul e versions.geul. Como ponteiros mutáveis não podem ser feitos como documento, verificam-se pela assinatura, pelo RECORDED-AT e pelo PARENT da lista recebida.

Signatário

AssinaturaSignatárioObjeto
Assinatura do documentoO Issuer do documentoHash de conteúdo do documento (Issuer e publicação)
Assinatura da listaO publicador que atribuiu os IDs de versãoHash de conteúdo da lista de versões
  • Na publicação em geul.org, geul.org (Issuer GEUL) atribui os IDs de versão e assina a lista; na publicação privada, é o próprio Issuer.
  • O autor responde pelo conteúdo e o publicador pelos números e pela ordem.

Verificação

  • A assinatura é excluída do hash de conteúdo, de modo que o hash permanece o mesmo se for removida. Por isso, verifica-se não com «se há assinatura, confira», mas com «deve haver a assinatura da chave determinada». As chaves exigidas são determinadas pela configuração de confiança do resolvedor e pelo registro de bloqueio.
  • O resolvedor registra no registro de bloqueio o hash de conteúdo da última lista vista. Se esse hash não está na cadeia de PARENT de uma lista recém-recebida, ela é rejeitada (impede retrocesso e bifurcação).
  • Espelhos e ambientes isolados copiam também a cadeia de listas de versões. Com a chave pública, a verificação é feita offline.
  • Um documento recebido, venha de qualquer origem, é verificado pelo hash de conteúdo. Não é preciso confiar na origem.

Resolução de dependências

  • O documento registra os documentos de que depende com IMPORT-DOC no HEAD.
  • Uma nova versão não promete compatibilidade com a anterior. Por isso, não se unifica em uma só a versão de um documento em todo o grafo (não se usa a seleção de versão mínima).
  • Cada IMPORT-DOC fica vinculado à edição que fixou. Várias edições do mesmo documento podem coexistir em um grafo (uma sentença que cita a lei antiga e outra que cita a lei vigente). As referências são resolvidas por (documento, versão, LOCAL ID).
  • Uma importação da mais recente (versão 0) vincula-se à edição mais recente no momento da interpretação. Se a interpretação é feita num instante determinado, vincula-se à edição em vigor naquele instante (documento).
  • Uma importação fixada por ID de versão é reproduzida (o conteúdo de um ID de versão é imutável e verificado pelo registro de bloqueio).

Tipo de mídia

  • O tipo de mídia dos documentos GEUL é application/vnd.geul. A extensão é .geul.
  • Mesmo que se mude para a árvore padrão application/geul, continua-se aceitando application/vnd.geul.

Problemas em aberto

  • O tratamento de quando os IDs de versão divergem (mesmo ID de versão, conteúdo diferente) em publicações privadas, Issuers de 16 WORD e ambientes isolados.
  • A composição do HEAD da lista de Issuers issuers/ e o formato de assinatura e cadeia. Regras de nome para Issuers sem domínio (4 WORD), tratamento de disputas de nome e limite de comprimento.
  • Quando e em que formato migrar, à medida que a lista cresce, da cadeia completa para um log Merkle (provas de inclusão e consistência).
  • O Meta que registra no HEAD o Issuer que fornece a localização.