Requirements Analyser API (/++requirements_analyser)

Endpoint:

POST /++requirements_analyser

---

1. Purpose

The Requirements Analyser service processes unstructured English text and extracts structured requirement-engineering artefacts such as:

• Actors

• Requirements

• Constraints

• Goals

• Vision statements

• User stories

• Use cases

• Scenarios

• States

The output is returned as table-ready JSON, designed to be rendered directly into UI tables.

---

2. Authentication & Access

Subscription Required

Access is protected by a subscription check:

If the subscription is invalid, the service will reject the request.

Possible Subscription Failure Response

{
  "error": "Subscription expired or invalid"
}

With an appropriate HTTP status code (e.g. 401 or 403).

---

3. HTTP Method & Headers

Method

POST

Required Header

Content-Type: application/json
Accept: application/json

---

4. Request Payload

4.1 JSON Schema

{
  "text": "string",
  "outputs": ["actors", "requirements"],
  "keywords": {
    "requirements": ["shall", "must"],
    "constraints": ["must not"]
  }
}

---

4.2 Request Fields

Field	Type	Required	Description
text	string	✅	The input text to analyse
outputs	array of strings	✅	Which tables to generate
keywords	object	❌	Optional keyword overrides

---

4.3 Supported outputs Values

The following output types are supported:

Output Key	Description
actors	Identified actors/roles
requirements	Requirement statements
constraints	Constraints & limitations
goals	Business or system goals
vision	Vision or long-term intent
user_stories	Agile user stories
use_cases	Use case statements
scenarios	Conditional scenarios
states	States or statuses

❗ Any unsupported output will cause the request to fail.

---

4.4 Keyword Override (Optional)

If no custom keywords are provided, default keywords are used.

Example default (requirements):

["shall", "must", "should", "needs to", "has to", "expected to"]

You may override keywords per category:

{
  "keywords": {
    "requirements": ["shall", "must"],
    "constraints": ["encrypted", "gdpr"]
  }
}

If a keyword list is empty or invalid, the service falls back to defaults.

---

5. Processing Logic (Important for Users)

NLP Engine

• Uses spaCy en_core_web_sm

• Language: English only

---

Actor Extraction Logic

Actors are extracted when:

• A token is a noun or proper noun

• AND its dependency role is:

  • nsubj (nominal subject)

  • nsubjpass (passive subject)

Actors are lemmatised and lower-cased.

---

Keyword-Based Extraction Logic

For all other outputs:

• Text is split into sentences

• A sentence is included if any keyword appears as a substring

• Matching is case-insensitive

• No semantic scoring or ML classification is applied

---

6. Response Format

6.1 Success Response

HTTP Status: 200 OK

{
  "tables": {
    "actors": { ... },
    "requirements": { ... }
  }
}

---

6.2 Table Object Structure

Each table follows the same structure:

{
  "id": "requirements",
  "title": "Requirements",
  "description": "Extracted requirements from text",
  "columns": ["ID", "Text"],
  "rows": [
    ["R-1", "The system shall allow users to log in."]
  ]
}

---

6.3 Actors Table Example

{
  "id": "actors",
  "title": "Actors",
  "description": "Identified roles and actors",
  "columns": ["ID", "Actor"],
  "rows": [
    ["A-1", "user"],
    ["A-2", "system"]
  ]
}

---

6.4 ID Format

Type	Format
Actors	A-1, A-2, ...
Requirements	R-1, R-2, ...
Constraints	C-1, C-2, ...
Goals	G-1, ...
Vision	V-1, ...
User Stories	U-1, ...
Use Cases	U-1, ...
Scenarios	S-1, ...
States	S-1, ...

(IDs are sequential per table.)

---

7. Error Handling

7.1 Validation Errors

HTTP Status: 400 Bad Request

{
  "error": "Field 'text' is mandatory"
}

Possible validation errors:

• Invalid JSON payload

• Missing or empty text

• Missing or empty outputs

• Unsupported output types

---

7.2 Server Errors

HTTP Status: 500 Internal Server Error

{
  "error": "Internal server error"
}

All internal exceptions are logged server-side.

---

8. Usage Example (cURL)

curl -X POST https://example.com/Plone/++requirements_analyser \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The system shall allow users to reset passwords.",
    "outputs": ["actors", "requirements"]
  }'

---

9. Intended Consumers

• Web frontends rendering editable tables

• Requirements management tools

• Educational platforms

• CSV / Excel export pipelines

• AI-assisted authoring tools

---

10. Known Limitations

• English language only

• Keyword-based (not semantic classification)

• spaCy model loaded per request

• No confidence scoring

• No sentence deduplication across categories

---

11. Versioning

Version	Notes
1.0	Initial external API

---

12. Summary

✔ Subscription-protected
✔ Predictable table output
✔ UI-friendly structure
✔ Safe keyword fallback
✔ No side effects (read-only)