DIRACGrid / DIRACGrid/dirac-cwl

Remove duplicate JSON schemas from test workflows and improve documentation

Open
#75 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3
Forks
4
PR merge metrics
No merged PRs in 30d

Description

We currently have a [JSON schema files](https://github.com/aldbr/dirac-cwl-proto/tree/a1900b590012ae03541dd90267298d4e5ba3c6d0/test/schemas) committed to the repository that is:
1. **Manually generated** from our Pydantic models
2. **Duplicated** because they are also deployed in Github Pages: this can create a potential source of truth conflict

This duplication can lead to divergence between the schema used in tests and deployed. While the schema serves as a reference for users implementing their own workflows, storing it in the test directory is probably not appropriate location for documentation.

### Proposed Solution
1. Audit** all test files to determine if JSON schemas are actually useful in any test
2. **If not used in tests**: Remove the file from the repository and update documentation to reference the deployed schema instead
3. **If used in tests**: Refactor tests to generate the schema dynamically from Pydantic models
4. **Update README** with clear references to where users can find authoritative schema documentation

## Tasks

- [ ] **Audit test files**
- [ ] Search codebase for all references to these JSON schemas
- [ ] Document which tests (if any) actually import or use this file
- [ ] Document which tests only reference it as an example

**Decision point**: Based on audit results, if not really useful
- [ ] Remove these JSON schema and their reference in the tests
- [ ] Add section to README to document the JSON Schema Reference (link to them if not already present, pros, how to use them in productions, transformations, jobs)

If they are actually needed, then we need to follow: https://github.com/aldbr/dirac-cwl-proto/pull/39#discussion_r2607539181

## Done criteria
**No duplicate schema files**
- The schema exists in exactly one authoritative location: generated and deployed to GitHub Pages
- No static schema files are committed to the repository

- Tests cannot fail due to stale schema files
- Tests validate the actual current implementation, not historical artifacts

**Documentation is clear**
- README has a dedicated section explaining where to find workflow schemas
- Direct link to deployed schema on GitHub Pages
- Clear examples for users implementing their own workflows

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.