Skip to content

Commit 19675f3

Browse files
psmaginpsmagin
authored
docs: create features documentation (#200)
1 parent 7019f0c commit 19675f3

11 files changed

Lines changed: 790 additions & 0 deletions

‎docs/features.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Module Features
2+
3+
This module provides the following features:
4+
5+
## Specification Management
6+
| Feature | Description |
7+
|------------------------------------------------------------------|----------------------------------------------------------------------------------------|
8+
| [Specification Retrieval](features/specification-retrieval.md) | Retrieve MARC specifications with filtering and optional inclusion of related entities |
9+
| [Specification Synchronization](features/specification-sync.md) | Reset specifications to default state by removing local customizations |
10+
11+
## Record Validation
12+
| Feature | Description |
13+
|---------------------------------------------------------------------------|---------------------------------------------------------------------------|
14+
| [Record Validation Against Specifications](features/record-validation.md) | Programmatic validation of MARC records against specification definitions |
15+
16+
## Validation Rules
17+
| Feature | Description |
18+
|----------------------------------------------------------------------------|---------------------------------------------------------------------------------|
19+
| [Specification Rule Management](features/specification-rule-management.md) | View and enable/disable validation rules with automatic audit metadata tracking |
20+
21+
## Field Definitions
22+
| Feature | Description |
23+
|------------------------------------------------------|------------------------------------------------------------------------------------------------|
24+
| [Field Management](features/field-management.md) | Retrieve all field definitions and create, update, or delete custom local field definitions |
25+
26+
## Subfield Definitions
27+
| Feature | Description |
28+
|----------------------------------------------------------|----------------------------------------------------------------------------------------------------|
29+
| [Subfield Management](features/subfield-management.md) | Retrieve all subfield definitions and create, update, or delete custom local subfield definitions |
30+
31+
## Indicator Definitions
32+
| Feature | Description |
33+
|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|
34+
| [Indicator Management](features/indicator-management.md) | Retrieve all indicator definitions, create and update custom indicators, and append indicator codes |
35+
36+
## Event-Driven Integration
37+
| Feature | Description |
38+
|--------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
39+
| [Specification Update Processing](features/specification-update-processing.md) | Process specification update requests via Kafka for event-driven synchronization |
40+
| [Specification Change Events](features/specification-change-events.md) | Publish event notifications when specification data is modified |

‎docs/features/field-management.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
feature_id: field-management
3+
title: Field Management
4+
updated: 2026-02-18
5+
---
6+
7+
# Field Management
8+
9+
## What it does
10+
Provides retrieval and management of MARC field definitions for a specification, including both standard fields (from the base specification) and local custom fields. Allows institutions to view all fields and create, update, or delete custom local field definitions for institution-specific cataloging needs.
11+
12+
## Why it exists
13+
Different institutions use local MARC field tags for institution-specific cataloging needs beyond the standard LOC-documented fields. This feature enables discovery of all valid fields and full customization of local field definitions, including indicators and subfields, supporting institution-specific cataloging practices while preserving the base specification.
14+
15+
## Entry point(s)
16+
17+
### Field Retrieval
18+
| Method | Path | Description |
19+
|--------|------|-------------|
20+
| GET | /specification-storage/specifications/{specificationId}/fields | Returns collection of all field definitions for the specification |
21+
22+
### Field Management
23+
| Method | Path | Description |
24+
|--------|------|-------------|
25+
| POST | /specification-storage/specifications/{specificationId}/fields | Creates a new local field definition |
26+
| PUT | /specification-storage/fields/{id} | Updates an existing field definition |
27+
| DELETE | /specification-storage/fields/{id} | Deletes a field definition |
28+
29+
## Business rules and constraints
30+
31+
### Field Retrieval
32+
- Response includes both standard specification fields and local custom fields
33+
- Each field definition includes:
34+
- Field tag (e.g., "001", "245")
35+
- Label and help URL
36+
- Required/repeatable flags
37+
- Indicator definitions
38+
- Subfield definitions
39+
- Deprecation status
40+
- Field order follows MARC field tag numeric ordering
41+
- Pagination is not applied (all fields returned)
42+
43+
### Field Management
44+
- **Field tag format**: Must be a 3-digit numeric string (e.g., "245", "900")
45+
- **Local field ranges**: Typically 9XX, X9X, XX9 (except 490 and 999), or any custom field not documented by Library of Congress
46+
- **Required fields**: `tag` and `label` are mandatory for create/update operations
47+
- **Field properties**:
48+
- `label`: Human-readable description (max 350 characters)
49+
- `url`: Optional help URL (max 350 characters, must be valid URL format with http/https protocol)
50+
- `repeatable`: Whether field can appear multiple times (default: `true`)
51+
- `required`: Whether field must be present (default: `false`)
52+
- `deprecated`: Mark field as deprecated (default: `false`)
53+
- **Tag uniqueness**: Cannot create a local field with the same tag as an existing field in the specification
54+
- **Local fields only**: Can only update/delete fields that were created locally; standard specification fields and system fields cannot be modified
55+
- **Full customization**: For local fields, tenants have complete control over all validation rules including indicators and subfields
56+
- **Cascading delete**: Deleting a field removes all associated subfields and indicators
57+
- **Sync impact**: Local fields are removed when specification is synced to defaults
58+
59+
## API response statuses
60+
- **200 OK**: Field definitions retrieved successfully
61+
- **201 Created**: Local field successfully created
62+
- **202 Accepted**: Field successfully updated
63+
- **204 No Content**: Field successfully deleted
64+
- **400 Bad Request**: Invalid specification ID or field data (malformed tag, missing required fields, invalid URL, tag already exists)
65+
- **404 Not Found**: Specification ID or field ID does not exist
66+
- **409 Conflict**: Attempting to modify or delete a standard (non-local) field
67+
- **500 Internal Server Error**: Database or system errors
68+
69+
## Configuration
70+
No feature-specific configuration required.
71+
72+
## Dependencies and interactions
73+
- Data sourced from PostgreSQL tables: `field`, `indicator`, `subfield`
74+
- Field definitions are initially loaded from bundled specification data during sync
75+
- Publishes events via [Specification Change Events](specification-change-events.md) after field changes
76+
- Local fields are removed during [Specification Synchronization](specification-sync.md) operations

‎docs/features/indicator-management.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
feature_id: indicator-management
3+
title: Indicator Management
4+
updated: 2026-02-18
5+
---
6+
7+
# Indicator Management
8+
9+
## What it does
10+
Provides retrieval and management of MARC field indicators and their valid code values, allowing institutions to view all indicators and create/update custom local indicator definitions and append local indicator codes to both standard and local fields. Enables discovery of indicator structures and customization for institution-specific cataloging needs.
11+
12+
## Why it exists
13+
MARC data fields use indicators (positions 1 and 2) with specific code values defined by Library of Congress. This feature enables discovery of valid indicator positions and code values, while also allowing institutions to define local indicators for custom fields and append additional local indicator codes to standard fields for institution-specific cataloging practices while preserving base LOC-documented definitions.
14+
15+
## Entry point(s)
16+
17+
### Indicator Retrieval
18+
| Method | Path | Description |
19+
|--------|------|-------------|
20+
| GET | /specification-storage/fields/{fieldId}/indicators | Returns all indicator definitions for a field |
21+
22+
### Indicator Management
23+
| Method | Path | Description |
24+
|--------|------|-------------|
25+
| POST | /specification-storage/fields/{fieldId}/indicators | Creates a new local indicator definition |
26+
| PUT | /specification-storage/indicators/{indicatorId} | Updates an existing indicator definition |
27+
28+
### Indicator Code Management
29+
| Method | Path | Description |
30+
|--------|------|-------------|
31+
| GET | /specification-storage/indicators/{indicatorId}/indicator-codes | Returns all code definitions for an indicator |
32+
| POST | /specification-storage/indicators/{indicatorId}/indicator-codes | Creates a new local code definition |
33+
| PUT | /specification-storage/indicator-codes/{indicatorCodeId} | Updates an existing code definition |
34+
| DELETE | /specification-storage/indicator-codes/{indicatorCodeId} | Deletes a code definition |
35+
36+
## Business rules and constraints
37+
38+
### Indicator Retrieval
39+
- Response includes both standard specification indicators and local custom indicators
40+
- Each indicator definition includes:
41+
- Order (position): 1 or 2
42+
- Label (description)
43+
- Collection of valid indicator codes with their labels
44+
- MARC fields can have 0, 1, or 2 indicators
45+
- Indicators are ordered by position (order 1 before order 2)
46+
- All indicators are returned (no pagination)
47+
48+
### Indicator Definitions
49+
- **Indicator order**: Must be 1 or 2 (representing first or second indicator position)
50+
- **Required fields**: `order` and `label` are mandatory for create/update operations
51+
- **Indicator properties**:
52+
- `order`: Indicator position (1 or 2)
53+
- `label`: Human-readable description (max 350 characters)
54+
- **Order uniqueness**: Cannot create an indicator with the same order as an existing indicator in the field (max 2 indicators per field)
55+
- **Local indicators only**: Can only update indicators that were created locally; standard specification indicators cannot be modified
56+
- **No delete endpoint**: Indicators cannot be deleted directly; delete the parent field to remove all indicators
57+
58+
### Indicator Code Definitions
59+
- **Code format**: Must be a single character (0-9, a-z lowercase, or # for blank/undefined)
60+
- **Required fields**: `code` and `label` are mandatory for create/update operations
61+
- **Code properties**:
62+
- `code`: Single character indicator value
63+
- `label`: Human-readable description of the code's meaning (max 350 characters)
64+
- `deprecated`: Mark code as deprecated (default: `false`)
65+
- **Code uniqueness**: Cannot create a code with the same value as an existing code in the indicator
66+
- **Standard vs Local codes**:
67+
- **Standard fields**: Cannot modify LOC-documented indicator codes, but can APPEND additional local indicator codes not specified by MARC
68+
- **Local fields**: Can fully customize all indicator codes
69+
- **System fields** (Leader, 001, 005, 245, 999, 006/007/008): Cannot modify indicator codes
70+
- **Undefined value representation**: Express undefined/blank indicator as `#` in API responses
71+
72+
### General Constraints
73+
- **Sync impact**: Local indicators and appended indicator codes are removed when specification is synced to defaults
74+
- **Cascading delete**: If parent field is deleted, all indicators and their codes are removed
75+
- **Cascading operations**: If parent indicator is deleted (via field deletion), all indicator codes are removed
76+
77+
## API response statuses
78+
- **200 OK**: Indicator or indicator code definitions retrieved successfully
79+
- **201 Created**: Local indicator or indicator code successfully created
80+
- **202 Accepted**: Indicator or indicator code successfully updated
81+
- **204 No Content**: Indicator code successfully deleted (indicators cannot be deleted directly)
82+
- **400 Bad Request**: Invalid field ID or indicator/code data (malformed code, missing required fields, order/code already exists, order out of range)
83+
- **404 Not Found**: Field ID, indicator ID, or indicator code ID does not exist
84+
- **409 Conflict**: Attempting to modify a standard (non-local) indicator/code, or order/code conflict
85+
- **500 Internal Server Error**: Database or system errors
86+
87+
## Configuration
88+
No feature-specific configuration required.
89+
90+
## Dependencies and interactions
91+
- Data sourced from PostgreSQL `indicator` and `indicator_code` tables
92+
- Indicator definitions loaded from bundled specification data during sync
93+
- Publishes events via [Specification Change Events](specification-change-events.md) after indicator or code changes
94+
- Local indicators and codes are removed during [Specification Synchronization](specification-sync.md) operations

‎docs/features/record-validation.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
feature_id: record-validation
3+
title: Record Validation Against Specifications
4+
updated: 2026-02-18
5+
---
6+
7+
# Record Validation Against Specifications
8+
9+
## What it does
10+
Provides programmatic validation of MARC bibliographic and authority records against specification definitions, checking records for compliance with field structures, indicator values, subfield requirements, and all enabled validation rules. Returns detailed validation errors with severity levels (WARN or ERROR) that determine whether the record can be saved or must be corrected.
11+
12+
## Why it exists
13+
Enables applications (primarily quickMARC) to validate MARC records during cataloging workflows (create/derive/edit operations), ensuring records conform to MARC standards and institution-specific cataloging rules. Supports quality control by catching validation errors early while allowing catalogers to proceed with warnings when appropriate.
14+
15+
## Entry point(s)
16+
This is a **library feature** provided by the `mod-record-specifications-validator` module, not a REST API endpoint. Applications integrate the validator programmatically:
17+
18+
```java
19+
SpecificationValidator validator = new MarcSpecificationValidator(translationProvider, converter);
20+
List<ValidationError> errors = validator.validate(marcRecord, specification);
21+
```
22+
23+
## Business rules and constraints
24+
- **Supported formats**: MARC bibliographic and authority records (MARC4J `Record` objects or custom `MarcRecord` model)
25+
- **Primary use case**: Validation for quickMARC create/derive/edit workflows
26+
- **Validation scope**: Only enabled rules for the specification are enforced (disabled rules are skipped)
27+
- **Validation behavior**:
28+
- **PREVENT SAVE (ERROR severity)**: Critical violations that prevent record from being saved
29+
- Required field is missing
30+
- Non-repeatable field appears multiple times
31+
- Required subfield is missing
32+
- Non-repeatable subfield appears multiple times
33+
- **WARN (WARNING severity)**: Non-critical violations that allow saving with warning
34+
- Invalid indicator code (not specified in rules)
35+
- Invalid subfield code (not specified in rules)
36+
- Undefined field (field not in validation list)
37+
- Deprecated field/subfield usage
38+
- **Validation categories**:
39+
- **Field-level validation**: Field presence, repeatability, deprecation, tag validity, 1XX field constraints
40+
- **Indicator validation**: Invalid indicator values, undefined indicator codes
41+
- **Subfield validation**: Subfield presence, repeatability, deprecation, undefined subfields, LCCN structure validation
42+
- **System fields** (validation rules cannot be changed): Leader, 001, 005, 245 (bib), 999, and control fields 006/007/008
43+
- **Validation errors include**:
44+
- `path`: Location in the record (e.g., `001`, `245$a`, `100[1]$d`)
45+
- `severity`: ERROR (prevent save) or WARNING (allow save with warning)
46+
- `definitionType`: Type of definition violated (FIELD, INDICATOR, SUBFIELD)
47+
- `definitionId`: UUID of the violated definition
48+
- `ruleCode`: Code of the violated rule (e.g., `undefinedField`, `missingSubfield`)
49+
- `message`: Localized human-readable error message
50+
- **Custom converters**: Applications can provide custom converters to validate non-standard MARC representations
51+
- **Translation support**: Error messages support internationalization via `TranslationProvider`
52+
53+
## Available Validation Rules
54+
55+
The validator enforces the following rules when enabled in the specification (see [Specification Rule Management](specification-rule-management.md) for complete rule descriptions):
56+
57+
### Field-Level Rules (8)
58+
- `undefinedField`, `deprecatedField`, `nonRepeatableField`, `missingField`
59+
- `invalidFieldValue`, `invalidFieldTag`
60+
- `nonRepeatable1XXField`, `nonRepeatableRequired1XXField`
61+
62+
### Indicator Rules (2)
63+
- `invalidIndicator`, `undefinedIndicatorCode`
64+
65+
### Subfield Rules (6)
66+
- `undefinedSubfield`, `deprecatedSubfield`, `nonRepeatableSubfield`
67+
- `missingSubfield`, `invalidSubfieldValue`, `invalidLccnSubfieldValue`
68+
69+
## API response statuses
70+
- **Invalid input**: Throws `IllegalArgumentException` if record type is unsupported or converter fails
71+
- **Validation success**: Returns empty list when record is valid
72+
- **Validation failures**: Returns list of `ValidationError` objects describing all violations
73+
- **Rule evaluation**: Only enabled rules are evaluated; disabled rules are silently skipped
74+
75+
## Configuration
76+
No configuration required. Validation behavior is entirely controlled by:
77+
- The specification definition provided at validation time
78+
- Which rules are enabled in that specification
79+
- The `TranslationProvider` implementation for error message localization
80+
81+
## Dependencies and interactions
82+
- **Input dependencies**:
83+
- `SpecificationDto`: Complete specification with fields, subfields, indicators, and enabled rules (obtained from specification retrieval APIs)
84+
- MARC record: MARC4J `Record` object or custom `MarcRecord` model
85+
- `TranslationProvider`: For localizing validation error messages
86+
- **Output**: List of `ValidationError` objects
87+
- **Library dependencies**:
88+
- `marc4j`: For MARC record parsing and conversion
89+
- `mod-record-specifications-dto`: For specification and error DTOs
90+
- **Integration pattern**: Applications retrieve specifications via [Specification Retrieval](specification-retrieval.md), then validate records programmatically using this library

0 commit comments

Comments
 (0)