DocumentaciónAEM as a Cloud ServiceGuía del usuario

Diseño de un esquema JSON para un formulario adaptable (componentes principales) creating-adaptive-forms-using-json-schema

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creado para:

  • Principiante
  • Intermedio
  • Usuario
  • Desarrollador
Versión
Vínculo del artículo
Foundation
Haga clic aquí
Componentes principales
Este artículo

Requisitos previos prerequisites

Crear un formulario adaptable basado en componentes principales utilizando un esquema JSON como modelo de formulario requiere una comprensión básica del esquema JSON. Se recomienda leer el siguiente contenido antes de este artículo.

Usar un esquema JSON como modelo de formulario using-a-json-schema-as-form-model

Adobe Experience Manager Forms admite la creación de un formulario adaptable basado en componentes principales utilizando un esquema JSON existente como modelo de formulario. Este esquema JSON representa la estructura en la que el sistema back-end de su organización produce o consume datos. El esquema JSON que utilice debe cumplir con las especificaciones v4.

Las funciones principales del uso de un esquema JSON son:

  • La estructura del JSON se muestra como un árbol en la pestaña Buscador de contenido en el modo de creación de un formulario adaptable. Puede arrastrar y agregar un elemento de la jerarquía JSON al formulario adaptable en función de los componentes principales.
  • Puede rellenar previamente el formulario utilizando un JSON que cumpla con el esquema asociado.
  • En el envío, los datos especificados por el usuario se envían como JSON, que se adhiere al esquema asociado.
  • También puede crear el formulario basado en el esquema JSON según las especificaciones de la versión 2012-20.

Un esquema JSON consta de tipos de elementos simples y complejos. Los elementos tienen atributos que agregan reglas al elemento. Cuando estos elementos y atributos se arrastran a un formulario adaptable, se asignan automáticamente a los componentes del formulario adaptable correspondientes.

Esta asignación de elementos JSON con componentes del formulario adaptable se produce de la siguiente forma:

"birthDate": {
              "type": "string",
              "format": "date",
              "pattern": "date{DD MMMM, YYYY}",
              "aem:affKeyword": [
                "DOB",
                "Date of Birth"
              ],
              "description": "Date of birth in DD MMMM, YYYY",
              }
Elemento, propiedades o atributos JSON.
Componente de formulario adaptable

Propiedades de cadena con restricción enum y enumNames.

Sintaxis.

{

"type" : "string",

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

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

}

Componente desplegable:

  • Los valores enumerados en enumNames se muestran en el cuadro desplegable.
  • Los valores enumerados en enum se utilizan para el cálculo.

Propiedad de la cadena con restricción de formato. Por ejemplo, correo electrónico y fecha.

Sintaxis.

{

"type" : "string",

"format" : "email"

}

  • El componente del correo electrónico se asigna cuando el tipo es una cadena y el formato es un correo electrónico.
  • El componente de cuadro de texto con validación se asigna cuando el tipo es una cadena y el formato es un nombre de host.

{

"type" : "string",

}

Campo de texto
propiedad numérica
Campo numérico con subtipo ajustado en flotante
propiedad entera
Campo numérico con subtipo ajustado en entero
propiedad booleana
Cambio
propiedad de objeto
Panel
propiedad de matriz
Panel repetible con el mínimo y máximo igual a minItems y maxItems respectivamente. Solo es compatible con matrices homogéneas. Por lo tanto, la restricción de elementos debe ser un objeto y no una matriz.

Propiedades de esquema comunes common-schema-properties

El formulario adaptable utiliza la información disponible en el esquema JSON para asignar cada campo generado. En particular:

  • La propiedad title sirve como etiqueta para los componentes del formulario adaptable.
  • La propiedad description se define como una descripción larga para un componente del formulario adaptable.
  • La propiedad default sirve como valor inicial de un campo del formulario adaptable.
  • La propiedad maxLength se establece como atributo maxlength del componente del campo de texto.
  • Las propiedades minimum, maximum, exclusiveMinimum y exclusiveMaximum se utilizan para el componente Cuadro numérico.
  • Para ser compatible con el intervalo de DatePicker component, se facilitan las propiedades de esquema JSON adicionales minDate y maxDate.
  • Las propiedades minItems y maxItems se utilizan para restringir el número de elementos/campos que se pueden agregar o quitar de un componente de panel.
  • La propiedad readOnly define el atributo readonly de un componente del formulario adaptable.
  • La propiedad required marca el campo del formulario adaptable como obligatorio, mientras que en el panel (donde el tipo es un objeto), los datos JSON finales enviados poseen campos con el valor vacío correspondiente a ese objeto.
  • La propiedad pattern se ajusta como el patrón de validación (expresión regular) en el formulario adaptable.
  • La extensión del archivo de esquema JSON debe mantenerse como .schema.json. Por ejemplo, <filename>.schema.json.

Ejemplo 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",
  },
  "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",
        },
        "address": {
          "type": "string"
        }
      }
      }
  }
  }

Los cambios clave de las especificaciones del esquema JSON V4 a la versión 2020-12 son los siguientes:

  • El ID se ha declarado como $id
  • las definiciones se han declarado como $defs

Definiciones de esquema reutilizables reusable-schema-definitions

Las claves de definición se utilizan para identificar esquemas reutilizables. Las definiciones de esquema reutilizables se utilizan para crear fragmentos. A continuación, se muestra un ejemplo de un esquema JSON con definiciones:

{
  "$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" }
  }
}

El ejemplo anterior define un registro de cliente en el que cada cliente tiene una dirección de envío y de facturación. La estructura de ambas direcciones es la misma (las direcciones tienen una dirección de calle, una ciudad y un estado), por lo que no se recomienda duplicar las direcciones. También facilita la el hecho de agregar o eliminar campos para cualquier cambio futuro.

Limitar los valores aceptables para un componente de formulario adaptable limit-acceptable-values-for-an-adaptive-form-component

Puede agregar las siguientes restricciones a los elementos del esquema JSON para limitar los valores aceptables para un componente principal del formulario adaptable:

Propiedad de esquema
Tipo de datos
Descripción
Componente
maximum
Cadena
Especifica el límite superior para valores numéricos y fechas. Se incluye el valor máximo de forma predeterminada.
  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha
minimum
Cadena
Especifica el límite inferior para valores numéricos y fechas. Se incluye el valor mínimo de forma predeterminada.
  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha
exclusiveMaximum
Booleano

Si es true, el valor numérico o la fecha especificados en el componente del formulario deben ser menores que el valor numérico o la fecha especificados para la propiedad máxima.

Si es false, el valor numérico o la fecha especificados en el componente del formulario deben ser menores o iguales al valor numérico o a la fecha especificados para la propiedad máxima.

  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha
exclusiveMinimum
Booleano

Si es true, el valor numérico o la fecha especificados en el componente del formulario deben ser mayores que el valor numérico o la fecha especificados para la propiedad mínima.

Si es false, el valor numérico o la fecha especificados en el componente del formulario deben ser mayores o iguales al valor numérico o la fecha especificados para la propiedad mínima.

  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha
minLength
Cadena
Especifica el número mínimo de caracteres permitidos en un componente. La longitud mínima debe ser igual o mayor de cero.
  • Cuadro de texto
maxLength
Cadena
Especifica el número máximo de caracteres permitidos en un componente. La longitud máxima debe ser igual o mayor de cero.
  • Cuadro de texto
pattern
Cadena

Especifica la secuencia de caracteres. Un componente acepta los caracteres si se ajustan al patrón especificado.

La propiedad pattern se asigna al patrón de validación del componente de formulario adaptable correspondiente.

  • Todos los componentes de formulario adaptable asignados a un esquema XSD
maxItems
Cadena
Especifica el número máximo de elementos de una matriz. Los elementos máximos deben ser iguales o superiores a cero.
minItems
Cadena
Especifica el número mínimo de elementos de una matriz. Los elementos mínimos deben ser iguales o superiores a cero.

Habilitar datos compatibles con esquemas enablig-schema-compliant-data

Para permitir que todos los Formularios adaptables basados en esquemas JSON generen datos compatibles con esquemas al enviar el formulario, siga estos pasos:

  1. Vaya a la consola web de Experience Manager en https://server:host/system/console/configMgr.
  2. Localizar Configuración del canal web de comunicaciones interactivas y formularios adaptables.
  3. Seleccione esta opción para abrir la configuración en modo de edición.
  4. Seleccione la casilla de verificación Generar datos compatibles con esquemas.
  5. Guarde la configuración.

Configuración de canal web de comunicaciones interactivas y formularios adaptables

Construcciones no compatibles non-supported-constructs

Los formularios adaptables no son compatibles con las siguientes construcciones de esquema JSON:

  • Tipo nulo
  • Tipos de unión, como any y
  • OneOf, AnyOf, AllOf y NOT
  • Solo es compatible con matrices homogéneas. Por lo tanto, la restricción de elementos debe ser un objeto y no una matriz.
  • Referencias de URI en $ref

Preguntas frecuentes frequently-asked-questions

¿Por qué no puedo arrastrar elementos individuales de un subformulario (estructura generada a partir de cualquier tipo complejo) para subformularios repetibles (los valores minOccours o maxOccurs son superiores a 1)?

En un subformulario repetible, debe utilizar el subformulario completo. Si solo le interesan los campos selectivos, utilice toda la estructura y elimine los no deseados.

Tengo una estructura larga y compleja en el Buscador de contenido. ¿Cómo puedo encontrar un elemento específico?

Tiene dos opciones:

  • Desplazarse por la estructura de árbol
  • Utilizar el cuadro Buscar para buscar un elemento

¿Cuál debe ser la extensión del archivo de esquema JSON?

La extensión del archivo de esquema JSON debe ser .schema.json. Por ejemplo, <filename>.schema.json.

¿Se admite aem:afProperties como parte del esquema JSON en Forms adaptable basado en componentes principales?

No, aem:afProperties no es compatible con los componentes principales. Esta propiedad solo se admite para componentes de base.

Consulte también see-also

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