"""Validate the proposed specification envelope and its cross-record invariants. No dependency is installed by this script. jsonschema is required for full Draft 2020-12 validation. Success does NOT authenticate actors, inspect referenced artifacts, establish the truth of evidence, or prove domain completeness. """ from __future__ import annotations import argparse from copy import deepcopy from importlib.metadata import version import json from pathlib import Path import sys def issue(code: str, path: str, message: str) -> dict: return {"code": code, "path": path, "message": message} def pointer(parts) -> str: return "/" + "/".join(str(p).replace("~", "~0").replace("/", "~1") for p in parts) def semantic_errors(doc: dict) -> list[dict]: """Called only after complete structural validation has succeeded.""" errors = [] def add(code, path, message): errors.append(issue(code, path, message)) collections = ("inputs", "requirements", "criteria", "tasks", "open_questions", "evidence") seen = {doc["id"]: "/id"} indexes = {} for collection in collections: index = {} for n, item in enumerate(doc[collection]): path = f"/{collection}/{n}/id" identifier = item["id"] if identifier in seen: add("ID_DUPLICATE", path, f"ID {identifier!r} already occurs at {seen[identifier]}.") else: seen[identifier] = path index[identifier] = item indexes[collection] = index def check_ref(identifier, collection, path): if identifier not in indexes[collection]: add("REFERENCE_MISSING", path, f"{identifier!r} does not name an item in {collection}.") for n, req in enumerate(doc["requirements"]): check_ref(req["source_ref"], "inputs", f"/requirements/{n}/source_ref") for n, criterion in enumerate(doc["criteria"]): for k, req_id in enumerate(criterion["requirement_ids"]): check_ref(req_id, "requirements", f"/criteria/{n}/requirement_ids/{k}") for n, task in enumerate(doc["tasks"]): for k, req_id in enumerate(task["requirement_ids"]): check_ref(req_id, "requirements", f"/tasks/{n}/requirement_ids/{k}") for k, criterion_id in enumerate(task["criterion_ids"]): check_ref(criterion_id, "criteria", f"/tasks/{n}/criterion_ids/{k}") criterion = indexes["criteria"].get(criterion_id) if criterion is not None: unknown_to_task = set(criterion["requirement_ids"]) - set(task["requirement_ids"]) if unknown_to_task: add("TASK_CRITERION_MISMATCH", f"/tasks/{n}/criterion_ids/{k}", f"Criterion {criterion_id!r} includes requirements absent from this task: {sorted(unknown_to_task)}.") for n, evidence in enumerate(doc["evidence"]): check_ref(evidence["criterion_id"], "criteria", f"/evidence/{n}/criterion_id") for n, evidence_id in enumerate(doc["acceptance"]["evidence_ids"]): check_ref(evidence_id, "evidence", f"/acceptance/evidence_ids/{n}") revisions = set() for n, change in enumerate(doc["change_log"]): if change["revision"] in revisions: add("REVISION_DUPLICATE", f"/change_log/{n}/revision", "Duplicate change-log revision.") revisions.add(change["revision"]) # Historical affected_ids may refer to items removed in later snapshots. # Only the current snapshot's change entry can be resolved here. if change["revision"] == doc["revision"]: for k, identifier in enumerate(change["affected_ids"]): if identifier not in seen: add("REFERENCE_MISSING", f"/change_log/{n}/affected_ids/{k}", f"Current revision refers to unknown affected ID {identifier!r}.") if doc["revision"] not in revisions: add("REVISION_UNLOGGED", "/change_log", "Current document revision has no change-log entry.") must_ids = {r["id"] for r in doc["requirements"] if r["priority"] == "must"} covered = {r for c in doc["criteria"] for r in c["requirement_ids"]} for req_id in sorted(must_ids - covered): add("MUST_UNCOVERED", "/criteria", f"Mandatory requirement {req_id!r} has no criterion.") required_criteria = { c["id"] for c in doc["criteria"] if must_ids.intersection(c["requirement_ids"]) } execution = doc["execution"] acceptance = doc["acceptance"] is_accepted = execution["status"] == "accepted" or acceptance["decision"] == "accept" if doc["status"] == "approved" or is_accepted: for n, req in enumerate(doc["requirements"]): if req["priority"] == "must" and not req["confirmed"]: add("MUST_UNCONFIRMED", f"/requirements/{n}/confirmed", "Approved or accepted work cannot contain unconfirmed mandatory requirements.") for n, question in enumerate(doc["open_questions"]): if question["blocking"] and not question["resolved"]: add("QUESTION_BLOCKING", f"/open_questions/{n}", "An unresolved blocking question prevents approval or acceptance.") if execution["status"] in {"submitted", "changes_requested", "accepted", "rejected"}: if not execution["artifact_ref"] or not execution["artifact_revision"]: add("ARTIFACT_REQUIRED", "/execution", "A submitted artifact reference and revision are required.") if acceptance["decision"] != "pending": for field in ("actor", "spec_revision", "artifact_revision", "decided_at"): if acceptance[field] is None: add("DECISION_INCOMPLETE", f"/acceptance/{field}", "A recorded decision requires this field.") decision_status = {"return": "changes_requested", "reject": "rejected"} required_status = decision_status.get(acceptance["decision"]) if required_status is not None and execution["status"] != required_status: add("DECISION_STATE_MISMATCH", "/execution/status", f"Decision {acceptance['decision']!r} requires execution status {required_status!r} in this snapshot.") if is_accepted: if execution["status"] != "accepted" or acceptance["decision"] != "accept": add("ACCEPTANCE_STATE_MISMATCH", "/acceptance/decision", "Execution accepted and acceptance accept must be recorded together.") if doc["status"] not in {"approved", "superseded", "retired"}: add("DOCUMENT_NOT_APPROVED", "/status", "A draft or in-review document cannot have accepted execution.") if acceptance["actor"] != doc["acceptor"]: add("ACCEPTOR_MISMATCH", "/acceptance/actor", "The actor ID must match the named acceptor; this is not authentication.") if acceptance["spec_revision"] != doc["revision"]: add("ACCEPTANCE_REVISION_STALE", "/acceptance/spec_revision", "Acceptance refers to another specification revision.") if acceptance["artifact_revision"] != execution["artifact_revision"]: add("ACCEPTANCE_REVISION_STALE", "/acceptance/artifact_revision", "Acceptance refers to another artifact revision.") if not doc["evidence"] or not acceptance["evidence_ids"]: add("ACCEPTANCE_EVIDENCE_REQUIRED", "/acceptance/evidence_ids", "Acceptance must select nonempty evidence.") selected = [indexes["evidence"][e] for e in acceptance["evidence_ids"] if e in indexes["evidence"]] def current(evidence): return (evidence["spec_revision"] == doc["revision"] and evidence["artifact_revision"] == execution["artifact_revision"]) for evidence in selected: if not current(evidence): add("EVIDENCE_STALE", "/acceptance/evidence_ids", f"Selected evidence {evidence['id']!r} refers to a different specification or artifact revision.") passed = {e["criterion_id"] for e in selected if current(e) and e["result"] == "pass"} for criterion_id in sorted(required_criteria - passed): add("MUST_CRITERION_NOT_PASSED", "/acceptance/evidence_ids", f"Mandatory criterion {criterion_id!r} lacks selected, current, passing evidence.") # Do not allow acceptance to hide a known current failure by not selecting it. for n, evidence in enumerate(doc["evidence"]): if current(evidence) and evidence["criterion_id"] in required_criteria and evidence["result"] == "fail": add("MUST_CRITERION_FAILED", f"/evidence/{n}", "A mandatory criterion has current failed evidence; resolve it in a new artifact revision.") return errors def validate_document(doc: dict, schema: dict) -> dict: try: from jsonschema import Draft202012Validator, FormatChecker except ImportError as exc: return { "valid": None, "stage": "dependency", "full_schema_validation": False, "semantic_validation": "not_run", "errors": [issue("DEPENDENCY_MISSING", "", "Full validation requires an importable Python jsonschema package; nothing was installed and no partial substitute was used. Import error: " + str(exc))], } try: Draft202012Validator.check_schema(schema) except Exception as exc: return {"valid": None, "stage": "schema_definition", "full_schema_validation": False, "semantic_validation": "not_run", "errors": [issue("SCHEMA_INVALID", "", str(exc))]} checker = FormatChecker() if checker.conforms("definitely-not-a-date", "date-time"): return {"valid": None, "stage": "dependency", "full_schema_validation": False, "semantic_validation": "not_run", "errors": [issue("FORMAT_CHECKER_MISSING", "", "A date-time format checker is unavailable; full declared checks were not performed.")]} schema_errors = sorted( Draft202012Validator(schema, format_checker=checker).iter_errors(doc), key=lambda error: pointer(error.absolute_path), ) if schema_errors: return { "valid": False, "stage": "structure", "full_schema_validation": True, "semantic_validation": "not_run", "errors": [issue("SCHEMA_VALIDATION", pointer(e.absolute_path), e.message) for e in schema_errors], } errors = semantic_errors(doc) return {"valid": not errors, "stage": "complete", "full_schema_validation": True, "semantic_validation": "completed", "errors": errors} def self_test(example: dict, schema: dict) -> dict: cases = [("valid_accepted_example_with_unconfirmed_unmapped_should", deepcopy(example), True, None)] def mutate(name, operation, code): specimen = deepcopy(example) operation(specimen) cases.append((name, specimen, False, code)) draft = deepcopy(example) draft["status"] = "draft" draft["execution"] = {"status": "not_started", "artifact_ref": None, "artifact_revision": None} draft["evidence"] = [] draft["acceptance"] = {"decision": "pending", "actor": None, "reason": "Draft awaits review.", "evidence_ids": [], "spec_revision": None, "artifact_revision": None, "decided_at": None} draft["requirements"][0]["confirmed"] = False draft["open_questions"][0]["resolved"] = False cases.append(("valid_draft_with_unresolved_question", draft, True, None)) should_failure = deepcopy(example) should_failure["criteria"].append({"id": "CRIT-SUMMARY", "requirement_ids": ["REQ-OPTIONAL-SUMMARY"], "method": "inspection", "procedure": "Inspect optional grouping of problems.", "expected": "Summary provided.", "evidence_required": True}) should_failure["evidence"].append({"id": "EVID-SUMMARY", "criterion_id": "CRIT-SUMMARY", "spec_revision": "r1", "artifact_revision": "artifact-r1", "result": "fail", "reference": "EXAMPLE: optional summary absent", "checker": "ROLE-FIELD-SUPERVISOR"}) cases.append(("valid_acceptance_with_failed_optional_should", should_failure, True, None)) for decision, execution_status in (("return", "changes_requested"), ("reject", "rejected")): snapshot = deepcopy(example) snapshot["acceptance"]["decision"] = decision snapshot["execution"]["status"] = execution_status cases.append((f"valid_{decision}_decision_snapshot", snapshot, True, None)) mutate("dangling_requirement_reference", lambda d: d["criteria"][0].update(requirement_ids=["REQ-MISSING"]), "REFERENCE_MISSING") mutate("task_references_existing_foreign_criterion", lambda d: d["tasks"][0].update( requirement_ids=["REQ-COVERAGE"], criterion_ids=["CRIT-FIELDS"]), "TASK_CRITERION_MISMATCH") mutate("duplicate_entity_id", lambda d: d["requirements"][1].update(id=d["requirements"][0]["id"]), "ID_DUPLICATE") mutate("stale_specification_evidence", lambda d: d["evidence"][0].update(spec_revision="r0"), "EVIDENCE_STALE") mutate("stale_artifact_evidence", lambda d: d["evidence"][0].update(artifact_revision="artifact-r0"), "EVIDENCE_STALE") mutate("accepted_without_evidence", lambda d: (d.update(evidence=[]), d["acceptance"].update(evidence_ids=[])), "ACCEPTANCE_EVIDENCE_REQUIRED") mutate("unresolved_blocking_question", lambda d: d["open_questions"][0].update(resolved=False), "QUESTION_BLOCKING") mutate("unconfirmed_must", lambda d: d["requirements"][0].update(confirmed=False), "MUST_UNCONFIRMED") mutate("must_without_criterion", lambda d: d["criteria"][0].update(requirement_ids=["REQ-FIELDS"]), "MUST_UNCOVERED") mutate("acceptor_actor_mismatch", lambda d: d["acceptance"].update(actor="EMPLOYEE-DEMO-01"), "ACCEPTOR_MISMATCH") mutate("accepted_without_submitted_artifact", lambda d: d["execution"].update(artifact_ref=None, artifact_revision=None), "ARTIFACT_REQUIRED") mutate("hidden_current_failure", lambda d: d["evidence"].append({**d["evidence"][0], "id": "EVID-FAIL", "result": "fail"}), "MUST_CRITERION_FAILED") mutate("accepted_draft", lambda d: d.update(status="draft"), "DOCUMENT_NOT_APPROVED") mutate("return_with_submitted_execution", lambda d: ( d["acceptance"].update(decision="return"), d["execution"].update(status="submitted")), "DECISION_STATE_MISMATCH") mutate("reject_with_submitted_execution", lambda d: ( d["acceptance"].update(decision="reject"), d["execution"].update(status="submitted")), "DECISION_STATE_MISMATCH") mutate("invalid_datetime", lambda d: d["acceptance"].update(decided_at="not-a-date"), "SCHEMA_VALIDATION") mutate("unknown_structural_field", lambda d: d.update(unsupported_field=True), "SCHEMA_VALIDATION") # If the full schema dependency is unavailable, exercise only the semantic # function on these controlled fixtures. This is a unit test, NOT a fallback # validator for arbitrary input documents. Schema-specific tests are skipped. probe = validate_document(example, schema) schema_available = probe.get("full_schema_validation", False) results = [] for name, specimen, expected_valid, expected_code in cases: if not schema_available and expected_code == "SCHEMA_VALIDATION": results.append({"name": name, "expected_valid": expected_valid, "actual_valid": None, "expected_code": expected_code, "observed_codes": [], "passed": None, "stage": "skipped", "validation_scope": "schema_unavailable", "errors": []}) continue if schema_available: result = validate_document(specimen, schema) validation_scope = "full_schema_and_semantic" else: errors = semantic_errors(specimen) result = {"valid": not errors, "stage": "semantic_unit_test", "errors": errors} validation_scope = "semantic_only_not_document_validation" codes = sorted({e["code"] for e in result["errors"]}) passed = result["valid"] == expected_valid and (expected_code is None or expected_code in codes) results.append({"name": name, "expected_valid": expected_valid, "actual_valid": result["valid"], "expected_code": expected_code, "observed_codes": codes, "passed": passed, "stage": result["stage"], "validation_scope": validation_scope, "errors": result["errors"]}) try: package_version = version("jsonschema") except Exception: package_version = None return { "artifact": "Author-proposed specification standard — synthetic validation cases", "schema_draft": "2020-12", "jsonschema_version": package_version, "full_validation_complete": schema_available, "dependency_probe": probe if not schema_available else {"stage": "available"}, "all_passed": schema_available and all(r["passed"] for r in results), "executed_tests_passed": all(r["passed"] for r in results if r["passed"] is not None), "tests_skipped": sum(r["passed"] is None for r in results), "tests_total": len(results), "positive_cases": sum(c[2] for c in cases), "negative_cases": sum(not c[2] for c in cases), "tests": results, "scope": "Without jsonschema, only semantic unit tests run on controlled fixtures; structural validity is unverified, schema tests are skipped, and the arbitrary-document validator fails closed. No field execution, artifact inspection, identity authentication, or real acceptance was performed.", } def main() -> int: base = Path(__file__).resolve().parent parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("document", nargs="?", type=Path, default=base / "specification.example.json") parser.add_argument("--schema", type=Path, default=base / "specification.schema.json") parser.add_argument("--self-test", action="store_true", help="Check the synthetic example and targeted in-memory mutations.") parser.add_argument("--output", type=Path, help="Write the JSON result to this path in addition to stdout.") args = parser.parse_args() try: schema = json.loads(args.schema.read_text(encoding="utf-8")) doc = json.loads(args.document.read_text(encoding="utf-8")) result = self_test(doc, schema) if args.self_test else validate_document(doc, schema) except (OSError, json.JSONDecodeError) as exc: result = {"valid": False, "stage": "input", "errors": [issue("INPUT_ERROR", "", str(exc))]} rendered = json.dumps(result, ensure_ascii=False, indent=2) if args.output: args.output.write_text(rendered + "\n", encoding="utf-8", newline="\n") # ensure_ascii keeps Windows consoles with a legacy encoding usable. print(json.dumps(result, ensure_ascii=True, indent=2)) if result.get("stage") in {"dependency", "schema_definition", "input"} or result.get("full_validation_complete") is False: return 2 return 0 if result.get("all_passed", result.get("valid", False)) else 1 if __name__ == "__main__": raise SystemExit(main())