En el Modelo Global de Soluciones, una norma es un conjunto de directrices que podrán ser de obligado cumplimiento o solo una recomendación, relativas al uso o aplicación de cualquier elemento de dicho modelo.
Consulta el Glosario de términos para una definición completa de norma.
Título
Nombre de la norma, se consigna en el campo Título, con la forma general "Norma para..." o "Norma de..." seguido de la finalidad.
- Debe hacer referencia únicamente a la norma.
- Evitar títulos que hagan referencia a varios tipos de recursos, por ejemplo “Normas y Estándares”.
Descripción
Se ha de utilizar el campo Descripción, que contendrá lo siguiente:
- Código: Código de la norma (por ejemplo "NOR_API")
- Versión vigente: Número de versión vigente, (por ejemplo "v01r00")
- Descripción concisa del contenido presentado, incluyendo el propósito de la norma. Evitar información redundante o excesivamente extensa, asegurando que el mensaje sea directo y comprensible.
Ámbito de aplicación de la norma
Este apartado se incluirá en primer lugar en el campo Contenido utilizando el rótulo "Ámbito de aplicación de la norma" en un encabezado de segundo nivel (Encabezado 2).
Recoge en qué situaciones y circunstancias se ha de cumplir la norma, para ello, hay que establecer de manera clara y precisa su alcance, especificando aspectos tales como los tipos de proyectos, la infraestructura, los componentes y/o las plataformas tecnológicos a las que se aplica. Además, puede incluir consideraciones adicionales sobre cómo la norma se relaciona con otras normas o estándares.
Es importante que esta sección sea lo más clara y detallada posible para evitar confusiones o interpretaciones erróneas sobre quiénes están obligados a cumplir la norma y en qué supuestos.
Incluir al final de este apartado, el texto:
"Puedes conocer en esta sección cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma."
Desarrollo de la norma
Apartados y subapartados que estructuran las directrices que desarrollan la norma y facilitan su comprensión y localización desde el índice de la página.
Se incluirá en el campo Contenido y se utilizarán los siguientes encabezados:
- El segundo nivel (Encabezado 2) para el título del apartado, que aparecerá de forma automática en el índice de la página.
- El tercer nivel (Encabezado 3) para los subapartados.
- El cuarto nivel (Encabezado 4) para las directrices.
Cómo redactar las directrices
La norma puede contener directrices de carácter obligatorio y/o recomendado, según su nivel de exigencia:
Obligatorias
- Son reglas estrictas que deben cumplirse sin excepciones.
- Se redactan usando el futuro de indicativo ("Todas las APIs estarán securizadas" o "Se usará AsyncAPI como estándar para definir las APIs"), el presente de indicativo en forma impersonal ("Se requiere la implementación de políticas para la retransmisión de mensajes") o usando el modo imperativo ("Utilice OpenAPI en su versión 3.1.X como estándar para definir las APIs"). Si es preciso, para reforzar la idea de obligatoriedad, se pueden utilizar términos como: "Debe", "Es obligatorio", "No se permite", tanto en su forma positiva como negativa..
Recomendadas
- Son directrices sugeridas que no requieren cumplimiento obligatorio, pero contribuyen a mejores prácticas.
- Se redactan en términos flexibles, como: "Se recomienda", "En la medida de lo posible". “Son opcionales”. Esta construcción puede hacerse tanto para su forma positiva como negativa.
El título de la directriz tendrá el siguiente formato:
- DIR_[nº de la directriz con dos dígitos] [Título de la directriz]
- Por ejemplo: NOR_API_04 Definición de APIs REST
Cada directriz tendrá un mensaje principal que se etiquetará de la siguiente forma según su nivel de obligatoriedad:
- Etiqueta con la siguiente apariencia: OBLIGATORIO, que se consigue utilizando el estilo de texto “info”, con el texto “OBLIGATORIO”.
- Etiqueta con la siguiente apariencia: RECOMENDADO, que se consigue utilizando el estilo de texto “Warning”, con el texto “RECOMENDADO”,
Si para cumplir la directriz, esta tiene, a su vez, criterios con diferentes niveles de obligatoriedad, se indicará de la siguiente forma, según su aplicación sea:
- Obligatoria: Se ha de destacar el verbo utilizado para reseñar tal obligatoriedad, en mayúsculas y negrita, por ejemplo: “Se DEBE”, “Se DEBEN”, “Es OBLIGATORIO”
- Opcional: Se ha de destacar el verbo utilizado en mayúsculas, por ejemplo: “Se RECOMIENDA”, “Es OPCIONAL”, “Es RECOMENDABLE”
- No permitida: Se ha de destacar el verbo utilizado para indicar lo que no se puede realizar, en mayúsculas y negrita, por ejemplo: “NO DEBE”, “NO DEBEN”, “NO SE PERMITE”
Versionado
Para crear las versiones, se ha de utilizar el tipo de contenido "Versión":
- Consulta la forma de crear versiones y asociarlas al recurso, tanto para normas como para otros recursos.
- Y las pautas de redacción del tipo de contenido Versión.
La norma ha de contener la versión vigente que, además, se encontrará enlazada en el apartado "Versiones". Dicho apartado se presenta automáticamente cuando la norma tenga asociada al menos un contenido tipo "Versión" publicado. Por tanto, el contenido tipo "Reglas y pautas" que contiene la norma:
- Tiene que estar asociado a sus diferentes versiones.
- Se tendrá que actualizar para que contenga la versión vigente de la norma.
Las versiones de las normas han de incluir:
- Los apartados correspondientes al ámbito de aplicación y al desarrollo de la norma, en el campo Contenido.
- Un apartado con el control o histórico de cambios entre versiones de la norma.