Sintaxis y palabras clave

EARS impone disciplina con un puñado de reglas. Esta sección las cubre una a una.

Las cuatro palabras clave de disparo

Palabra	Patrón	Significado
When	Event-driven	El sistema reacciona a un evento puntual
While	State-driven	El sistema mantiene comportamiento en un estado
Where	Optional feature	El requisito aplica solo si X está presente
If	Unwanted behaviour	Condición no deseada (siempre seguida de then)

Regla: usá la palabra correcta. While the user clicks está mal — un clic es puntual, va con When. When the user is authenticated está mal — la autenticación es un estado, va con While.

El verbo shall

EARS recomienda fuertemente shall como verbo modal de obligación. Razones:

• Es inequívoco: significa “obligatorio”.
• No tiene connotaciones de tiempo o probabilidad como will, should o may.
• Es el estándar en documentos normativos (ISO, RFC, IEEE).

Otros verbos modales y su significado en requisitos:

Verbo	Significado	Uso en EARS
shall	Obligatorio	Default — usalo siempre
should	Recomendado	Evitar — no es un requisito firme
may	Opcional	Evitar — convertí en optional feature
will	Declarativo	Evitar — no expresa obligación
must	Obligatorio	Aceptable, pero shall es preferido

En español: si escribís en español, usá “deberá” o “debe” de forma consistente. Mezclar “podrá”, “debería” y “deberá” genera ambigüedad.

Sujeto explícito

El requisito siempre nombra al sujeto. No “se hará X”, sino “el sistema hará X”. Eso elimina la voz pasiva y deja claro quién es responsable.

- La validación se realizará al enviar el formulario.
+ When the user submits the form, the validation service shall validate the input fields against the schema.

Granularidad del sujeto: cuanto más específico, mejor. “El sistema” funciona en requisitos de alto nivel. “El servicio de pagos”, “la capa de persistencia”, “el módulo de autenticación” funcionan mejor en requisitos detallados.

Respuesta verificable

Toda respuesta debe ser observable y medible. Si no podés escribir un test que la valide, no es un requisito EARS válido.

- ...the system shall be fast.
+ ...the system shall respond within 200 ms for the 95th percentile under 1000 concurrent users.

- ...the system shall handle errors gracefully.
+ If the database connection times out, then the API shall return HTTP 503 with a Retry-After header set to 30 seconds.

Patrones de respuesta verificable:

• Tiempos: within X ms, for the Nth percentile
• Códigos: HTTP 4xx, error code E001
• Formatos: JSON, UTF-8, ISO 8601
• Cardinalidad: at most N, at least N, exactly N
• Estado: transition to state X, persist X in the database

Orden de los elementos

EARS permite cierto orden, pero prefiere precondiciones antes del sujeto:

[Where ...] [While ...] When ... the <subject> shall <response>.

O alternativamente:

If ..., then the <subject> shall <response>.

Bien:

Where the user has admin privileges, while the audit mode is enabled, when a record is deleted, the system shall log the action to the audit trail with the user ID, timestamp, and affected record ID.

Mal (orden caótico):

The system shall log to the audit trail, where the user is admin, when records are deleted, while in audit mode.

Una sola respuesta por requisito

Cada requisito EARS describe una acción. Si hay múltiples, partilo.

- When the order is paid, the system shall send a confirmation email and update the inventory and notify the warehouse.
+ When the order is paid, the system shall send a confirmation email to the customer.
+ When the order is paid, the inventory service shall decrement the stock by the ordered quantity.
+ When the order is paid, the warehouse system shall receive a fulfillment request.

Excepción: si dos acciones son atómicas e inseparables (transaccionales), pueden coexistir conectadas por and:

If the payment fails, then the checkout service shall preserve the cart contents and shall display the error message to the user.

Acá preserve y display son dos efectos de un único error, no son separables a nivel de requisito.

Voz activa siempre

- The data will be encrypted before storage.
+ Before persisting user data, the persistence layer shall encrypt the data using AES-256-GCM.

La voz pasiva oculta al actor. EARS la prohíbe.

Evitá referencias circulares y prosa

EARS no soporta:

• “Como se mencionó arriba…” (cada requisito debe ser autónomo)
• “Etc.” (enumerá todo o usá una clase: “all HTTP methods listed in RFC 7231”)
• “Y/o” (and/or — decidite por uno)
• “Aproximadamente” (poné el número exacto o un rango)

Numeración y trazabilidad

Cada requisito EARS recibe un identificador único estable. Convención común:

REQ-<area>-<numero>: <texto EARS>

Por ejemplo:

REQ-AUTH-014: When the user submits the login form, the authentication service shall validate the credentials and shall issue a session token valid for 24 hours.

El ID permite trazar el requisito a través de specs, tests, código y documentación.

Resumen de reglas

1. Una sola acción por requisito
2. Sujeto explícito (nada de pasivas)
3. shall como verbo modal
4. Respuesta verificable (observable y medible)
5. Palabras clave correctas según patrón (When/While/Where/If-Then)
6. Sin “etc”, “y/o”, “aproximadamente”
7. ID único y trazable

En el siguiente capítulo vemos cómo combinar patrones para requisitos con múltiples precondiciones.