Histórico da Página

Um De acordo com as definições para JsonSchema, um campo declarado dentro a da mensagem deve conter obrigatoriamente as propriedades: 

• Typetype: Indica o tipo de dado do campo, mais detalhes consultar o tópico Tipos de dados padrão.
• Descriptiondescription: é importante que a descrição esteja bem detalhada, lembre-se que para o analista que está propondo um campo, o objetivo deste campo é sempre muito óbvio, porém próximos analistas do mesmo produto ou até analistas de outros produtos sempre terão dificuldade caso o campo não esteja bem documentado.
• x-totvs: propriedade customizada com a documentação referente ao campo em cada produto Totvs. 
  • Clique aqui para mais detalhes sobre x-totvs

...

Os nomes dos campos na mensagem única devem respeitar as regras a seguir:Devem ser sempre

Nomes escritos em inglês

...

Procure discutir com outras pessoas com conhecimento da língua inglesa ou pesquisar no Google Translator a tradução correta dos termos. Deve-se prestar muita atenção na possibilidade de ocorrerem os falsos cognatos.

...

Devem respeitar a formatação em Upper CamelCase com a primeira letra maiúscula.

ExemploExemplos
CustomerCode RegisterDate ListOfItem TypeOfDay

...

Ao criar o elemento que representa a chave primária da mensagem utilize apenas a palavra Code, quando for chave simples. Exemplo: na mensagem Seller, use Code e Description/Name.

ExemploExemplos
Mensagem  ItemMensagem Item    Code    Description    Status    RegisterDate

Ao utilizar esta uma chave primária como chave estrangeira em outra mensagem, utilize o padrão “Mensagem” + “Code”, ou seja, ItemCode, CustomerCode, BankCode. Exemplo: Na mensagem SalesOrder use SellerCode. 

ExemplosExemplo
Mensagem Warehouse    Code    Description
Mensagem Item    Code    Description    Status    RegisterDate    WarehouseCode

Reaproveitamento de nomes

Deve-se evitar a utilização de nomes diferentes para campos com o mesmo objetivo. Por isso, por isso ao criar os nomes de campos para uma mensagem é importante verificar em outras mensagens qual termo está sendo utilizado para o mesmo objetivo.

Utilize nomes que reflitam a descrição e vice-versa

Âncora
stnd-types stnd-types

Tipos de dados padrões

Texto

type: string

"CompanyCode": {
 "type": "string"
}

...

"CreditLimit":{
 "type":"number",
 "format":"double"
}

Propriedades de validação

...

Para objetos de tipos externos, deve-se utilizar a propriedade $ref, indicando a url do schema desejado, seguido de #/componentsdefinitions/schemas/[nome do schema].

"CommunicationInformation": {
	"$ref": "httphttps://apiraw.totvsgithubusercontent.com.br/schema/totvs/ttalk-standard-message/master/jsonschema/schemas/types/ContactInformation_1_000.json#/components/schemasdefinitions/CommunicationInformationType",
	"description": "Informações para Contato",
	"type": "object"
}

...

"type":"array",
"items": {
   "type": "string"
}

"type":"array",
"items": {
    "properties": {
          "bankCode": {
          	"note": "Código do banco",
          	"type": "integer",
          	"format": "int32"
		   }
	}
}

"type":"array",
"items":{
	"$ref": "https://apigithub.totvs.com.brcom/totvs/ttalk-standard-message/blob/master/jsonschema/schemas/types/Address_2_000.json/#/componentsdefinitions/schemas/AddressInfoAddressType"
}

...

Obrigatoriedade

No yaml arquivo do JsonSchema, as propriedades devem ser definidas como não obrigatórias, pois as mensagens únicas são utilizadas tanto para inclusão quando para exclusão. Ou seja, uma exclusão não precisa enviar tantas informações quanto a inclusão. Se a mensagem única tivesse os seus campos obrigatórios geraria a necessidade de se enviar o registro completo para exclusão e não apenas a sua chave.

Além disso, a obrigatoriedade de um campo depende de cada produto, o que torna muito mais difícil chegar a um consenso se for necessário considerar esta característica na modelagem da mensagem.

Por isso, ao declarar o schema, não se deve inserir a propriedade required :para os campos.

Campos que se repetem poderão apresentar um padrão diferente, consulte o tópico Criando listas de valores e elementos para mais informações.

...

Não é necessário montar mensagens específicas para tabelas que só precisarão trafegar código + e descrição. Estas informações poderão trafegar como chave estrangeira na mensagem que as utilizar. Também não é necessário criar agrupadores específicos para estes campos, podem ser colocados na raiz das mensagens.

Exemplo: HipoteticamenteConsidere, hipoteticamente, que a mensagem Item deverá levar a entidade Item esteja relacionada à informação do fabricante.Mensagem Item

   Code

   Description

   ManufacturerCode

   ManufacturerDescription

Por exemplo: Não existe a necessidade de criar a mensagem Manufacturer (supondo que contém apenas Código + Descrição). Estes dados deverão ser enviados na mensagem de Item.

Âncora
valores_fixos valores_fixos

Campos com valores fixos

Campos com valores fixos devem ser definidos como type: com tipo String e seus valores respeitar a sequencia devem ser uma sequência numérica (1,2,3,4 etc...). O objetivo desta definição é evitar confusões pelo uso de letras iguais para objetivos diferentes entre os produtos TOTVS. Exemplo: RM, Pedido Cancelado = “C”; Datasul, Datasul Pedido Concluído = “C”. Utilizando sempre a sequência numérica o desenvolvedor se vê obrigado a observar a lista de valores presentes na mensagem, observando inclusive se o tipo que queira utilizar já está listado no YAMLna definição da mensagem.

Porém, muitas vezes quando há casos em que um campo em um produto é composto por uma lista fixa de valores, enquanto em outro produto esses valores podem ser cadastrados dinamicamente. Exemplo: Tipo do documento no Logix é fixo, ; no Protheus é pre-cadastrado e permite alterar, na ; no Datasul é fixo e na no RM é totalmente cadastrável. Para estes casos leia o tópico Conflito entre valores fixos e valores cadastráveis.

"SubscriptionType": {
	"type": "string",
	"example": "pesquisar1",
	"description": "UnidadeTipo de Negócioinscrição",
	"enum": ["1",
	"2",
	"3",
	"4"],
	"x-totvs": [{
		"product": "protheus",
		"field": "SM0.M0_TPINSC",
		"required": false,
		"type": "Char",
		"length": "1",
		"avialableavailable": true,
		"canUpdate": false,
		"note": "1=CEI;2=CNPJ;3=CPF;4=INCRA"
	}]
}

...