DocumentaçãoAEM as a Cloud ServiceGuia do usuário

Criar um esquema JSON para um Formulário adaptável creating-adaptive-forms-using-json-schema

Last update: Tue Jan 28 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Criado para:

  • Iniciante
  • Intermediário
  • Usuário
  • Desenvolvedor
Versão
Link do artigo
Componentes principais
Clique aqui
Foundation
Este artigo
NOTE
A Adobe recomenda o uso de Componentes principais de captura de dados moderna e extensível para criar um novo Forms Adaptável ou adicionar o Adaptive Forms às páginas do AEM Sites. Esses componentes representam um avanço significativo na criação do Forms adaptável, garantindo experiências de usuário impressionantes. Este artigo descreve a abordagem mais antiga para criar o Forms adaptável usando componentes de base.
Versão
Link do artigo
AEM 6.5
Clique aqui
AEM as a Cloud Service
Este artigo

Pré-requisitos prerequisites

A criação de um formulário adaptável usando um Esquema JSON como seu modelo de formulário requer compreensão básica do Esquema JSON. É recomendável ler o conteúdo a seguir antes deste artigo.

Utilização de um esquema JSON como modelo de formulário using-a-json-schema-as-form-model

O Adobe Experience Manager Forms oferece suporte à criação de um Formulário adaptável usando um Esquema JSON existente como o modelo de formulário. Esse esquema JSON representa a estrutura em que os dados são produzidos ou consumidos pelo sistema de back-end em sua organização. O Esquema JSON usado deve ser compatível com especificações v4.

Os principais recursos do uso de um Esquema JSON são:

  • A estrutura do JSON é exibida como uma árvore na guia Localizador de conteúdo no modo de criação de um Formulário adaptável. Você pode arrastar e adicionar elemento da hierarquia JSON ao Formulário adaptável.
  • Você pode preencher previamente o formulário usando o JSON compatível com o esquema associado.
  • No envio, os dados inseridos pelo usuário são enviados como JSON, que se alinha ao esquema associado.
  • Você também pode criar o formulário com base no esquema JSON de acordo com as especificações da versão 2012-20.

Um Esquema JSON consiste em tipos de elementos simples e complexos. Os elementos têm atributos que adicionam regras ao elemento. Quando esses elementos e atributos são arrastados para um Formulário adaptável, eles são mapeados automaticamente para o componente de Formulário adaptável correspondente.

Esse mapeamento de elementos JSON com componentes de Formulário adaptável é o seguinte:

"birthDate": {
              "type": "string",
              "format": "date",
              "pattern": "date{DD MMMM, YYYY}",
              "aem:affKeyword": [
                "DOB",
                "Date of Birth"
              ],
              "description": "Date of birth in DD MMMM, YYYY",
              "aem:afProperties": {
                "displayPictureClause": "date{DD MMMM, YYYY}",
                "displayPatternType": "date{DD MMMM, YYYY}",
                "validationPatternType": "date{DD MMMM, YYYY}",
                "validatePictureClause": "date{DD MMMM, YYYY}",
                "validatePictureClauseMessage": "Date must be in DD MMMM, YYYY format."
              }
  }
Elemento JSON, propriedades ou atributos
Componente de formulário adaptável

Propriedades de string com restrições enum e enumNames.

Sintaxe,

{

"type" : "string",

"enum" : ["M", "F"]

"enumNames" : ["Male", "Female"]

}

Componente suspenso:

  • Os valores listados em enumNames são exibidos na caixa suspensa.
  • Os valores listados na enumeração são usados para cálculo.

Propriedade de cadeia de caracteres com restrição de formato. Por exemplo, email e data.

Sintaxe,

{

"type" : "string",

"format" : "email"

}

  • O componente de email é mapeado quando o tipo é string e o formato é email.
  • O componente Caixa de texto com validação é mapeado quando o tipo é string e o formato é hostname.

{

"type" : "string",

}

Campo de texto
propriedade numérica
Campo numérico com subtipo definido como flutuante
propriedade inteira
Campo Numérico com subtipo definido como inteiro
propriedade booleana
Alternar
propriedade de objeto
Painel
propriedade de matriz
Painel repetível com mín. e máx. iguais a minItems e maxItems, respectivamente. Somente matrizes homogêneas são compatíveis. Portanto, a restrição de itens deve ser um objeto e não uma matriz.

Propriedades comuns do esquema common-schema-properties

O Formulário adaptável usa as informações disponíveis no Esquema JSON para mapear cada campo gerado. Em especial:

  • A propriedade title serve como rótulo para os componentes do Formulário adaptável.
  • A propriedade description é definida como descrição longa para um componente de Formulário adaptável.
  • A propriedade default serve como valor inicial de um campo de Formulário adaptável.
  • A propriedade maxLength está definida como atributo maxlength do componente de campo de texto.
  • As propriedades minimum, maximum, exclusiveMinimum e exclusiveMaximum são usadas para o componente de Caixa Numérica.
  • Para dar suporte ao intervalo de DatePicker component, são fornecidas as propriedades adicionais do Esquema JSON minDate e maxDate.
  • As propriedades minItems e maxItems são usadas para restringir o número de itens/campos que podem ser adicionados ou removidos de um componente do painel.
  • A propriedade readOnly define o atributo readonly de um componente de Formulário adaptável.
  • A propriedade required marca o campo Formulário adaptável como obrigatório, enquanto no painel (em que o tipo é objeto), os dados JSON enviados finais têm campos com valor vazio que correspondem a esse objeto.
  • A propriedade pattern é definida como o padrão de validação (expressão regular) no Formulário adaptável.
  • A extensão do arquivo de Esquema JSON deve ser mantida em .schema.json. Por exemplo, <nome do arquivo>.schema.json.

Exemplo de esquema JSON sample-json-schema

Esquema JSON v4
code language-json 
{
"$schema": "https://json-schema.org/draft-04/schema#",
"definitions": {
  "employee": {
  "type": "object",
  "properties": {
    "userName": {
     "type": "string"
   },
    "dateOfBirth": {
     "type": "string",
     "format": "date"
    },
    "email": {
    "type": "string",
    "format": "email"
    },
    "language": {
     "type": "string"
   },
    "personalDetails": {
     "$ref": "#/definitions/personalDetails"
   },
    "projectDetails": {
     "$ref": "#/definitions/projectDetails"
    }
  },
  "required": [
   "userName",
   "dateOfBirth",
   "language"
  ]
  },
    "personalDetails": {
   "type": "object",
  "properties": {
     "GeneralDetails": {
    "$ref": "#/definitions/GeneralDetails"
   },
    "Family": {
     "$ref": "#/definitions/Family"
    },
    "Income": {
     "$ref": "#/definitions/Income"
   }
   }
     },
  "projectDetails": {
   "type": "array",
   "items": {
   "properties": {
   "name": {
    "type": "string"
   },
   "age": {
    "type": "number"
   },
   "projects": {
    "$ref": "#/definitions/projects"
   }
  }
 },
 "minItems": 1,
 "maxItems": 4
},
"projects": {
 "type": "array",
 "items": {
  "properties": {
   "name": {
    "type": "string"
   },
   "age": {
    "type": "number"
   },
   "projectsAdditional": {
    "$ref": "#/definitions/projectsAdditional"
   }
  }
 },
 "minItems": 1,
 "maxItems": 4
},
"projectsAdditional": {
 "type": "array",
 "items": {
  "properties": {
   "Additional_name": {
    "type": "string"
   },
   "Additional_areacode": {
    "type": "number"
   }
  }
 },
 "minItems": 1,
 "maxItems": 4
},
"GeneralDetails": {
 "type": "object",
 "properties": {
  "age": {
   "type": "number"
  },
  "married": {
   "type": "boolean"
  },
  "phone": {
   "type": "number",
   "aem:afProperties": {
    "sling:resourceType": "/libs/fd/af/components/guidetelephone",
    "guideNodeClass": "guideTelephone"
   }
  },
  "address": {
   "type": "string"
  }
 }
},
"Family": {
 "type": "object",
 "properties": {
  "spouse": {
   "$ref": "#/definitions/spouse"
  },
  "kids": {
   "$ref": "#/definitions/kids"
  }
 }
},
"Income": {
 "type": "object",
 "properties": {
  "monthly": {
   "type": "number"
  },
  "yearly": {
   "type": "number"
  }
 }
},
"spouse": {
 "type": "object",
 "properties": {
  "name": {
   "type": "string"
  },
  "Income": {
   "$ref": "#/definitions/Income"
  }
 }
},
"kids": {
 "type": "array",
 "items": {
  "properties": {
   "name": {
    "type": "string"
   },
   "age": {
    "type": "number"
   }
  }
 },
 "minItems": 1,
 "maxItems": 4
}
},
"type": "object",
"properties": {
"employee": {
 "$ref": "#/definitions/employee"
}
}
}
Esquema JSON 2012-20
code language-json 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/employee.schema.json",
  "$defs": {
    "employee": {
      "type": "object",
      "properties": {
        "userName": {
          "type": "string"
        },
        "dateOfBirth": {
          "type": "string",
          "format": "date"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "language": {
          "type": "string"
        },
        "personalDetails": {
          "$ref": "#/$defs/personalDetails"
        },
        "projectDetails": {
          "$ref": "#/$defs/projectDetails"
        }
      },
      "required": [
        "userName",
        "dateOfBirth",
        "language"
      ]
    },
    "personalDetails": {
      "type": "object",
      "properties": {
        "GeneralDetails": {
          "$ref": "#/$defs/GeneralDetails"
        },
        "Family": {
          "$ref": "#/$defs/Family"
        },
        "Income": {
          "$ref": "#/$defs/Income"
        }
      }
    },
    "projectDetails": {
      "type": "array",
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "projects": {
            "$ref": "#/$defs/projects"
          }
        }
      },
      "minItems": 1,
      "maxItems": 4
    },
    "projects": {
      "type": "array",
      "items": {
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "number"
          },
          "projectsAdditional": {
            "$ref": "#/$defs/projectsAdditional"
          }
        }
      },
      "minItems": 1,
      "maxItems": 4
    },
    "projectsAdditional": {
      "type": "array",
      "items": {
        "properties": {
          "Additional_name": {
            "type": "string"
          },
          "Additional_areacode": {
            "type": "number"
          }
        }
      },
      "minItems": 1,
      "maxItems": 4
    },
    "GeneralDetails": {
      "type": "object",
      "properties": {
        "age": {
          "type": "number"
        },
        "married": {
          "type": "boolean"
        },
        "phone": {
          "type": "number",
          "aem:afProperties": {
            "sling:resourceType": "/libs/fd/af/components/guidetelephone",
            "guideNodeClass": "guideTelephone"
          }
        },
        "address": {
          "type": "string"
        }
      }
      }
  }
  }

As principais alterações das especificações do Esquema JSON V4 para a versão 2020-12 são:

  • ID declarada como $id
  • definições são declaradas como $defs

Definições de esquema reutilizáveis reusable-schema-definitions

As chaves de definição são usadas para identificar esquemas reutilizáveis. As definições de esquema reutilizáveis são usadas para criar fragmentos. Um exemplo de esquema JSON com definições é fornecido abaixo:

{
  "$schema": "https://json-schema.org/draft-04/schema#",

  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "type": "object",

  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": { "$ref": "#/definitions/address" }
  }
}

O exemplo acima define um registro de cliente, em que cada cliente tem um endereço de entrega e de cobrança. A estrutura de ambos os endereços é a mesma — os endereços têm endereço, cidade e estado — portanto, é uma boa ideia não duplicar os endereços. Também facilita a adição e a exclusão de campos para qualquer alteração futura.

Pré-configuração de campos na definição do esquema JSON pre-configuring-fields-in-json-schema-definition

Você pode usar a propriedade aem:afProperties para pré-configurar o campo de Esquema JSON para mapear para um componente de Formulário adaptável personalizado. Um exemplo está listado abaixo:

{
    "properties": {
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512,
            "aem:afProperties" : {
                 "sling:resourceType" : "/apps/fd/af/components/guideTextBox",
                 "guideNodeClass" : "guideTextBox"
             }
        }
    },
    "required": [ "sizeInMB" ],
    "additionalProperties": false
}

Limitar valores aceitáveis para um componente de Formulário adaptável limit-acceptable-values-for-an-adaptive-form-component

Você pode adicionar as seguintes restrições aos elementos do Esquema JSON para limitar os valores aceitáveis para um componente de Formulário adaptável:

Propriedade do esquema
Tipo de dados
Descrição
Componente
maximum
String
Especifica o limite superior para valores numéricos e datas. Por padrão, o valor máximo é incluído.
  • Caixa numérica
  • Escalonador Numérico
  • Seletor de data
minimum
String
Especifica o limite inferior para valores numéricos e datas. Por padrão, o valor mínimo é incluído.
  • Caixa numérica
  • Escalonador numérico
  • Seletor de data
exclusiveMaximum
Booleano

Se true, o valor numérico ou a data especificada no componente do formulário deverá ser menor que o valor numérico ou a data especificada para a propriedade máxima.

Se false, o valor numérico ou a data especificada no componente do formulário deve ser menor ou igual ao valor numérico ou à data especificada para a propriedade maximum.

  • Caixa numérica
  • Escalonador numérico
  • Seletor de data
exclusiveMinimum
Booleano

Se true, o valor numérico ou a data especificada no componente do formulário deverá ser maior que o valor numérico ou a data especificada para a propriedade minimum.

Se false, o valor numérico ou a data especificada no componente do formulário deve ser maior ou igual ao valor numérico ou à data especificada para a propriedade minimum.

  • Caixa numérica
  • Escalonador numérico
  • Seletor de data
minLength
String
Especifica o número mínimo de caracteres permitidos em um componente. O comprimento mínimo deve ser igual ou maior que zero.
  • Caixa de texto
maxLength
String
Especifica o número máximo de caracteres permitidos em um componente. O comprimento máximo deve ser igual ou maior que zero.
  • Caixa de texto
pattern
String

Especifica a sequência dos caracteres. Um componente aceita os caracteres se eles estiverem em conformidade com o padrão especificado.

A propriedade padrão mapeia para o padrão de validação do componente de Formulário adaptável correspondente.

  • Todos os componentes adaptáveis do Forms mapeados para um esquema XSD
maxItems
String
Especifica o número máximo de itens em uma matriz. O máximo de itens deve ser igual ou maior que zero.
minItems
String
Especifica o número mínimo de itens em uma matriz. Os itens mínimos devem ser iguais ou maiores que zero.

Ativar dados compatíveis com o esquema enablig-schema-compliant-data

Para permitir que todo o Forms adaptável baseado em esquema JSON gere dados compatíveis com o esquema no envio do formulário, siga estas etapas:

  1. Vá para o Experience Manager web console em https://server:host/system/console/configMgr.
  2. Localize Configuração de Canal da Web de Comunicação entre Interações e Formulários Adaptáveis.
  3. Selecione para abrir a configuração no modo de edição.
  4. Marque a caixa de seleção Gerar dados compatíveis com o esquema.
  5. Salve as configurações.

configuração do canal da Web de formulário adaptável e comunicação interativa

Construções não suportadas non-supported-constructs

O Forms adaptável não é compatível com as seguintes construções de esquema JSON:

  • Tipo nulo
  • Tipos de união, como qualquer um, e
  • OneOf, AnyOf, AllOf e NOT
  • Somente matrizes homogêneas são compatíveis. Portanto, a restrição de itens deve ser um objeto e não uma matriz.
  • Referências de URI em $ref

Perguntas frequentes frequently-asked-questions

Por que não consigo arrastar elementos individuais de um subformulário (estrutura gerada de qualquer tipo complexo) para subformulários repetíveis (valores minOccours ou maxOccurs são maiores que 1)?

Em um subformulário repetível, você deve usar o subformulário completo. Se desejar apenas campos seletivos, use a estrutura inteira e exclua os indesejados.

Tenho uma estrutura complexa longa no Localizador de Conteúdo. Como posso encontrar um elemento específico?

Você tem duas opções:

  • Rolar pela estrutura de árvore
  • Use a caixa Pesquisar para localizar um elemento

Qual deve ser a extensão do arquivo de esquema JSON?

A extensão do arquivo de esquema JSON deve ser .schema.json. Por exemplo, <nome do arquivo>.schema.json.

Consulte também see-also

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab