Mapeamento entre JSON e XML

Os leitores e gravadores produzidos por JsonReaderWriterFactory mostram um API de XML sobre o conteúdo JSON (JavaScript Object Notation). O JSON codifica dados usando um subconjunto de literais de objeto do JavaScript. Os leitores e gravadores produzidos por este alocador também são usados quando o conteúdo JSON está sendo enviado ou recebido por aplicativos do WCF (Windows Communication Foundation) usando WebMessageEncodingBindingElement ou WebHttpBinding.

Quando inicializado com conteúdo JSON, o leitor JSON se comporta da mesma forma que um leitor de XML textual em uma instância de XML. O gravador JSON, quando dada uma sequência de chamadas que um leitor de XML textual produz uma determinada instância XML, grava o conteúdo JSON. O mapeamento entre essa instância de XML e o conteúdo JSON é descrito neste tópico para uso em cenários avançados.

Internamente, o JSON é representado como um infoset de XML quando processado pelo WCF. Normalmente, você não precisa se preocupar com essa representação interna, pois o mapeamento é apenas lógico: o JSON normalmente não é convertido fisicamente em XML na memória ou convertido em JSON de XML. O mapeamento significa que as APIs de XML são usadas para acessar o conteúdo JSON.

Quando o WCF usa JSON, o cenário usual é que DataContractJsonSerializer é conectado automaticamente pelo comportamento WebScriptEnablingBehavior ou pelo comportamento WebHttpBehavior quando apropriado. O DataContractJsonSerializer entende o mapeamento entre JSON e o infoset de XML e atua como se estivesse lidando diretamente com JSON. (É possível usar DataContractJsonSerializer com qualquer leitor ou gravador XML, com a compreensão de que o XML está em conformidade com o mapeamento a seguir.)

Em cenários avançados, pode ser necessário ter acesso direto ao mapeamento a seguir. Esses cenários ocorrem quando você deseja serializar e desserializar o JSON de forma personalizada, sem depender do DataContractJsonSerializer ou ao lidar com o tipo Message diretamente para mensagens que contêm JSON. O mapeamento JSON-XML também é usado para registro em log de mensagens. Ao usar o recurso de registro em log de mensagens no WCF, as mensagens JSON são registradas como XML de acordo com o mapeamento descrito na próxima seção.

Para esclarecer o conceito de um mapeamento, o exemplo a seguir é de um documento JSON.

{"product":"pencil","price":12}

Para ler este documento JSON usando um dos leitores mencionados anteriormente, use a mesma sequência de chamadas XmlDictionaryReader que você faria para ler o documento XML a seguir.

<root type="object">
    <product type="string">pencil</product>
    <price type="number">12</price>
</root>

Além disso, se a mensagem JSON no exemplo for recebida pelo WCF e registrada em log, você veria o fragmento XML no log anterior.

Mapeamento entre JSON e XML Infoset

Formalmente, o mapeamento é feito entre JSON, conforme descrito no RFC 4627 (exceto com determinadas restrições flexibilizadas e outras restrições adicionadas) e o XML Infoset (e não XML textual), conforme descrito no XML Information Set. Consulte este tópico para obter as definições de itens de informações e campos em [colchetes].

Um documento JSON em branco mapeia um documento XML em branco e um documento XML em branco mapeia um documento JSON em branco. No mapeamento XML para JSON, o espaço em branco anterior e o espaço em branco à direita após o documento não são permitidos.

O mapeamento é definido entre um DII (Document Information Item) ou um EII (Element Information Item) e JSON. O EII, ou a propriedade [elemento de documento] do DII, é chamado de Elemento JSON Raiz. Observe que não há suporte para fragmentos de documento (XML com vários elementos raiz) neste mapeamento.

Exemplo: o seguinte documento:

<?xml version="1.0"?>
<root type="number">42</root>

E o elemento a seguir:

<root type="number">42</root>

Ambos têm um mapeamento para JSON. O elemento <root> é o Elemento JSON Raiz em ambos os casos.

Além disso, no caso de um DII, deve ser considerado:

• Alguns itens na lista [filhos] não devem estar presentes. Não confie nesse fato ao ler XML mapeado do JSON.

• A lista [filhos] não contém itens de informações de comentário.

• A lista [filhos] não contém itens de informações DTD.

• A lista [filhos] não contém itens de informações de PI (informações pessoais) (a declaração <?xml…> não é considerada um item de informações de PI)

• O conjunto [notações] está vazio.

• O conjunto [entidades não analisadas] está vazio.

Exemplo: o documento a seguir não tem mapeamento para JSON porque [filhos] contém um PI e um comentário.

<?xml version="1.0"?>
<!--comment--><?pi?>
<root type="number">42</root>

O EII para o elemento raiz JSON tem as seguintes características:

• [nome local] tem o valor "raiz".

• [nome do namespace] não tem valor.

• [prefixo] não tem valor.

• [filhos] podem conter EIIs (que representam elementos internos conforme descrito abaixo) ou CIIs (Itens de informações de caracteres, conforme descrito abaixo) ou nenhum deles, mas não nos dois.

• [atributos] podem conter os seguintes itens de informações de atributo opcionais (AIIs)

• O atributo de tipo JSON ("tipo") conforme descrito abaixo. Esse atributo é usado para preservar o tipo JSON (cadeia de caracteres, número, booliano, objeto, matriz ou nulo) no XML mapeado.

• O atributo nome do contrato de dados ("__type") conforme descrito abaixo. Esse atributo somente pode estar presente se o atributo de tipo JSON também estiver presente e seu [valor normalizado] for "objeto". Esse atributo é usado por DataContractJsonSerializer para manter as informações de tipo de contrato de dados, por exemplo, em casos polimórficos em que um tipo derivado é serializado e onde um tipo base é esperado. Se você não estiver trabalhando com DataContractJsonSerializer, na maioria dos casos, esse atributo será ignorado.

• [namespaces no escopo] contém a associação de "XML" para http://www.w3.org/XML/1998/namespace, conforme exigido pela especificação do infoset.

• [filhos], [atributos] e [namespaces no escopo] não devem ter nenhum item diferente do especificado anteriormente e [atributos de namespace] não devem ter membros, mas não dependem desses fatos ao ler XML mapeado do JSON.

Exemplo: o documento a seguir não tem mapeamento para JSON porque [atributos de namespace] não está vazio.

<?xml version="1.0"?>
<root xmlns:a="myattributevalue">42</root>

O AII para o atributo de tipo JSON tem as seguintes características:

• [nome do namespace] não tem valor.
• [prefixo] não tem valor.
• [nome local] é "tipo".
• [valor normalizado] é um dos valores de tipo possíveis descritos na seção a seguir.
• [especificado] é true.
• [tipo de atributo] não tem valor.
• [referências] não tem valor.

O AII para o Atributo de Nome do Contrato de Dados tem as seguintes características:

• [nome do namespace] não tem valor.
• [prefixo] não tem valor.
• [nome local] é "__type" (dois sublinhados e, em seguida, "type").
• [valor normalizado] é qualquer cadeia de caracteres Unicode válida – o mapeamento dessa cadeia de caracteres para JSON é descrito na seção a seguir.
• [especificado] é true.
• [tipo de atributo] não tem valor.
• [referências] não tem valor.

Elementos internos contidos no elemento raiz JSON ou em outros elementos internos têm as seguintes características:

• [nome local] pode ter qualquer valor, conforme descrito abaixo.
• [nome do namespace], [prefixo], [filhos], [atributos], [atributos de namespace], e [namespaces no escopo] estão sujeitos às mesmas regras que o elemento raiz JSON.

No elemento raiz JSON e nos elementos internos, o Atributo de Tipo JSON define o mapeamento para JSON e os possíveis [filhos] e sua interpretação. O [valor normalizado] do atributo diferencia maiúsculas de minúsculas e deve ser minúsculo e não pode conter espaço em branco.

Os Registros de Membro funcionam:

• O [nome local] do elemento interno é mapeado para a parte string do member conforme definido na seção 2.2 do JSON RFC.

Exemplo: o seguinte elemento é mapeado para um fragmento JSON.

<root type="object">
    <myLocalName type="string">aaa</myLocalName>
</root>

O fragmento JSON a seguir é exibido.

{"myLocalName":"aaa"}

• No mapeamento XML para JSON, os caracteres que devem ser escapados no JSON são escapados e os outros não são escapados. O caractere "/", embora não seja um caractere de escape, é escapado (ele não precisa ser escapado no mapeamento JSON para XML). É necessário para dar suporte ao formato AJAX em ASP.NET para dados DateTime no JSON.

• No mapeamento JSON para XML, todos os caracteres (incluindo os caracteres não escapados, se necessário) são usados para formar um string que produza um [nome local].

• Elementos internos [filhos] mapeiam o valor na seção 2.2, de acordo com JSON Type Attribute assim como Root JSON Element. Vários níveis de aninhamento de EIIs (incluindo aninhamento dentro de matrizes) são permitidos.

Exemplo: o seguinte elemento é mapeado para um fragmento JSON.

<root type="object">
    <myLocalName1 type="string">myValue1</myLocalName1>
    <myLocalName2 type="number">2</myLocalName2>
    <myLocalName3 type="object">
        <myNestedName1 type="boolean">true</myNestedName1>
        <myNestedName2 type="null"/>
    </myLocalName3>
</root >

O fragmento JSON a seguir é o que ele mapeia.

{"myLocalName1":"myValue1","myLocalName2":2,"myLocalName3":{"myNestedName1":true,"myNestedName2":null}}

A situação inversa (caracteres válidos em XML, mas não em JSON) não causa problemas porque o mapeamento anterior inclui etapas de escape/não escape de JSON.

Os registros de matriz funcionam da seguinte forma:

• O [nome local] do elemento interno é "item".

• Os [filhos] do elemento interno são mapeados para o valor na seção 2.3, de acordo com o Atributo de Tipo JSON, assim como para o elemento raiz JSON. Vários níveis de aninhamento de EIIs (incluindo aninhamento dentro de matrizes) são permitidos.

Exemplo: o seguinte elemento é mapeado para um fragmento JSON.

<root type="array">
    <item type="string">myValue1</item>
    <item type="number">2</item>
    <item type="array">
    <item type="boolean">true</item>
    <item type="null"/></item>
</root>

Veja a seguir o fragmento JSON.

["myValue1",2,[true,null]]

Confira também

• JsonReaderWriterFactory
• DataContractJsonSerializer
• Serialização JSON autônoma