Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Formato de dados do documento: JSON estendido

JSON é um formato de dados que representa os valores de objetos, arrays, números, strings, booleans e nulos. O formato Extended JSON define um conjunto reservado de chaves prefixadas com o caractere $ para representar informações de tipos de campo que correspondem diretamente a cada tipo em BSON, o formato usado MongoDB para armazenar dados.

O MongoDB Extended JSON apresenta diferentes formatos de string para representar dados BSON. Cada um dos formatos está em conformidade com o JSON RFC e atende a casos de uso específicos.

O formato estendido, também conhecido como formato canônico, apresenta representações específicas para cada tipo BSON para conversão bidirecional sem perda de informações. O formato Relaxed é mais conciso e semelhante ao JSON comum, mas não representa todas as informações de tipo, como o tamanho de byte específico de campos numéricos.

A tabela a seguir fornece descrições dos formatos JSON:

Nome
Descrição

Extended

Também conhecido como o formato canônico, essa representação do JSON evita a perda de informações do tipo de BSON.
Esse formato prioriza a preservação do tipo na perda de legibilidade humana e interoperabilidade com formatos mais antigos.

Modo relaxado

Representação JSON que descreve documentos BSON com algum tipo de perda de informação.
Esse formato prioriza a legibilidade humana e a interoperabilidade na perda de determinados tipos de informações.

Shell

Representação JSON que corresponde à sintaxe usada no MongoDB shell.
Esse formato prioriza a compatibilidade com o shell do MongoDB, que frequentemente usa funções JavaScript para representar tipos.

Strict

Obsoleto Essa representação é o formato legado que está totalmente em conformidade com o JSON RFC e permite que qualquer analisador JSON leia as informações de tipo.

Para saber mais sobre JSON, BSON e Extended JSON, consulte nosso artigo sobre JSON e BSON e a referência de Extended JSON no manual do MongoDB Server.

As seguintes abas mostram um documento contendo um campo de ObjectId, data e número longo representado em cada formato Extended JSON. Selecione nas guias para ver os mesmos dados apresentados em cada formato JSON:

{ "_id": { "$oid": "573a1391f29313caabcd9637" }, "createdAt": { "$date": { "$numberLong": "1601499609" }}, "numViews": { "$numberLong": "36520312" }}

Você pode ler uma string de JSON estendida em uma estrutura Go ligando para o método bson.UnmarshalExtJSON(). Este método analisa uma string de JSON estendida e armazena o resultado no parâmetro de valor especificado.

Este exemplo mostra como você pode ler uma string de JSON estendida na seguinte estrutura Person:

type Person struct { ID bson.ObjectID `bson:"_id"` Name string Age int Birthday bson.DateTime Address Address Hobbies []string} type Address struct { Street string City string State string}

O código abaixo usa o método UnmarshalExtJSON() para ler uma string de JSON estendida e desordenar os dados em uma instância de Person:

var extJsonString = "{\"_id\":{\"$oid\":\"578f6fa2df35c7fbdbaed8c5\"},\"name\":\"Liana Ruiz\",\"age\":46,\"birthday\":{\"$date\":\"1988-01-15T00:00:00Z\"},\"address\":{\"street\":\"500 Slippery Rock Road\",\"city\":\"Round Rock\",\"state\":\"AR\"},\"hobbies\":[\"cycling\", \"baking\"]}" var p Personerr := bson.UnmarshalExtJSON([]byte(extJsonString), false, &p)if err != nil { log.Fatal(err)} fmt.Printf("Go Struct Representation:\n%+v\n", p)

Aviso

Valide entradas não confiáveis antes de converter JSON em BSON

Se você converter uma string JSON para BSON e usar o BSON resultante em uma query, atualizar ou comando, um invasor pode injetar operadores ou valores de campo inesperados que alteram o significado da operação. Esse risco é maior quando o JSON se origina de um usuário, uma solicitação de API ou outra fonte não confiável.

Para aprender mais sobre como validar a entrada antes da conversão, consulte Validar entrada não confiável antes de converter JSON em BSON.

Você pode produzir uma string de JSON estendida a partir de uma instância de uma estrutura Go ou documento BSON chamando o método bson.MarshalExtJSON(). O exemplo abaixo cria uma string de Extended JSON no formato Relaxed a partir de uma estrutura ou de um documento BSON. Selecione a aba Struct ou bson.D para ver o exemplo correspondente:

var person = Person{ ID: bson.NewObjectID(), Name: "Matteo Carisi", Age: 49, Birthday: bson.NewDateTimeFromTime(time.Date(1975, 10, 30, 0, 0, 0, 0, time.UTC)), Address: Address{Street: "14a Corner Court", City: "Springfield", State: "IL"}, Hobbies: []string{"cooking", "birdwatching"},} newExtJsonStringFromStruct, err := bson.MarshalExtJSON(person, false, true)if err != nil { log.Fatal(err)} fmt.Printf("Extended JSON Representation:\n%s\n", newExtJsonStringFromStruct)

O segundo parâmetro para MarshalExtJSON() determina se a string de saída está no formato canônico (estendido) ou formato relaxado. O exemplo anterior passa false como o parâmetro canonical, então a saída é JSON relaxado.

Observação

Datas anteriores à hora da época

Quando você empacota um valor de data que é anterior a 1 de janeiro, 1970, 00:00:00 UTC (horário de época), ele aparece como um carimbo de data/hora Unix em JSON relaxado. Se a data for posterior à hora da época, ela aparecerá em um formato de data legível.

Você pode usar o método bson.MarshalExtJSONIndent() para imprimir uma string de JSON estendida formatada que inclui novas linhas, prefixos e recuo.

O código a seguir usa o método MarshalExtJSONIndent() para imprimir a string JSON do exemplo anterior formatada com dois espaços de recuo:

formattedString, err := bson.MarshalExtJSONIndent(person, false, true, "", " ")if err != nil { log.Fatal(err)} fmt.Printf("%s\n", formattedString)

Para saber mais sobre os métodos e tipos usados neste guia, consulte a seguinte documentação da API: