De acordo com as definições para JsonSchema, um campo declarado dentro da mensagem deve conter obrigatoriamente as propriedades:
Os nomes dos campos na mensagem única devem respeitar as regras a seguir:
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.
Exemplo: Código do Turno é ShiftCode e não TurnCode e nem CodeOfTurn. Turn em inglês significa: transformar, voltar, vez e não “turno”, é um caso de falso cognato.
Devem respeitar a formatação em Upper CamelCase com a primeira letra maiúscula.
Exemplos |
---|
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.
Exemplos |
---|
Mensagem Item Code Description Status RegisterDate |
Ao utilizar uma chave primária como chave estrangeira em outra mensagem, utilize o padrão “Mensagem” + “Code”, ou seja, ItemCode, CustomerCode, BankCode.
Exemplos |
---|
Mensagem Warehouse Code Description |
Mensagem Item Code Description Status RegisterDate WarehouseCode |
Deve-se evitar a utilização de nomes diferentes para campos com o mesmo objetivo. 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.
Exemplos |
---|
Utilizar sempre CompanyId e BranchId para empresa e filial. Utilizar sempre ItemCode pois este já é utilizado em todas as mensagens que usam a chave primária da mensagem Item. Não utilizar ProductCode, a mensagem para produto é a Item. Utilizar VendorCode para código do representante e não Suplier e nem Provider, pois a mensagem já existente é CustomerVendor. |
Hoje já existe a mensagem Role, que representa Cargo no Logix. O Cargo do Logix corresponde a Função no Protheus. Então novas mensagens propostas pelo Protheus têm que usar o termo Role para Função e não Function ou JobTitle (possíveis nomes para a mensagem de Cargo).
Utilize nomes que reflitam a descrição e vice-versa
Exemplos reais e proposta de correção |
---|
TableCodeItem - Código da Tabela de Preços (Deveria ser PriceListCode ou PriceTableCode) SalesPrice - Preço de mínimo de venda do produto (Deveria ser MinimumSalesPrice) |
type: string
"CompanyCode": { "type": "string" }
maxLength | tamanho máximo do texto. Deve ser um valor inteiro maior que 0. |
minLength | tamanho mínimo do texto. Deve ser um valor inteiro maior que 0. |
pattern | string com expressão regular. |
Exemplo | |
---|---|
minLength: 2, | Válido: "22" ; "11" Inválido: "aa" ; "1"; "123" |
type: integer
format: int32
"BankCode": { "description": "Código do banco", "type": "integer", "format": "int32" }
type: integer
format: int64
"BankCode": { "description": "Código do banco", "type": "integer", "format": "int64" }
type: number
format: float
"UnitsPerHour": { "type": "number", "format": "float" }
type: number
format: double
"CreditLimit":{ "type":"number", "format":"double" }
minimum | menor valor possível para o campo. ex: -9999999.999 |
maximum | maior valor possível para o campo. ex: 9999999.999 |
multipleOf | define que apenas múltiplos deste valor podem ser atribuídos ao campo |
Para definir precisão e escala de números com ponto flutuante, deve-se utilizar essas 3 propriedades.
Exemplo | ||
---|---|---|
precisão: 10 escala: 3 | minimum: -9999999.999 maximum: 9999999.999 multipleOf: 1e-3 | Válido: 123.12 ; 000.254 Inválido: 123.4565 ; 0000.55484 |
type: boolean
"IsPayer":{ "type":"boolean" }
type: string
format: date
"Registerdate":{ "type": "string", "format": "date" }
type: string
format: date-time
"Registerdate":{ "type": "string", "format": "date-time" }
type: object
Deve conter o atributo properties, o qual será um objeto com n propriedades.
"CreditInformation": { "type": "object", "properties": { "CreditIndicator": { "type": "integer", "format": "int32" } } }
Para objetos de tipos externos, deve-se utilizar a propriedade $ref, indicando a url do schema desejado, seguido de #/definitions/[nome do schema].
"CommunicationInformation": { "$ref": "https://raw.githubusercontent.com/totvs/ttalk-standard-message/master/jsonschema/schemas/types/ContactInformation_1_000.json#/definitions/CommunicationInformationType", "description": "Informações para Contato", "type": "object" }
type: array
Deve conter o atributo items, o qual deverá conter uma das seguintes opções:
type | Quando array de tipos comuns (string, integer, number, boolean, etc) | "type":"array", "items": { "type": "string" } |
properties | Quando for array de objetos | "type":"array", "items": { "properties": { "bankCode": { "note": "Código do banco", "type": "integer", "format": "int32" } } } |
$ref | Quando array de objetos externos | "type":"array", "items":{ "$ref": "https://github.com/totvs/ttalk-standard-message/blob/master/jsonschema/schemas/types/Address_2_000.json/#/definitions/AddressType" } |
Por definição todo campo ListOf deve ser array.
minItems | valor mínimo de items do array. |
maxItems | valor máximo de items do array. |
No 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.
Havendo a necessidade de validação da presença ou não de informação na mensagem, este controle deve ser feito no próprio adapter.
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: Considere, hipoteticamente, que a entidade Item esteja relacionada à informação do fabricante.
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.
Exemplo |
---|
Mensagem Item Code Description ManufacturerCode ManufacturerDescription |
Campos com valores fixos devem ser definidos com tipo String e seus valores 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, 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 na definição da mensagem.
Porém, 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; no Datasul é fixo e no RM é totalmente cadastrável. Para estes casos leia o tópico Conflito entre valores fixos e valores cadastráveis.
"SubscriptionType": { "type": "string", "example": "1", "description": "Tipo de inscrição", "enum": ["1", "2", "3", "4"], "x-totvs": [{ "product": "protheus", "field": "SM0.M0_TPINSC", "required": false, "type": "Char", "length": "1", "available": true, "canUpdate": false, "note": "1=CEI;2=CNPJ;3=CPF;4=INCRA" }] }
https://tools.ietf.org/html/draft-wright-json-schema-validation-00
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#dataTypes