gemaraproj / gemaraproj/website

Generated schema pages do not show inherited fields from embedded structs

Open
#11 0 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
Go
Stars
0
Forks
4
Avg merge
7d 3h
Merged PRs (30d)
2

Description

## Summary 🤖

When [work here ](https://github.com/gemaraproj/gemara/pull/478) is ready and merged, Gemara OpenAPI generator will represent embedded CUE definitions with OpenAPI composition:

```
ControlCatalog:
allOf:
- $ref: "#/components/schemas/Catalog"
properties:
controls: ...
```

This is valid and preserves the source model, but schema reference pages must resolve `allOf` to display inherited properties and required fields.

Without resolution, pages for schemas such as ControlCatalog, ThreatCatalog, GuidanceCatalog, and log types omit fields inherited from their base schemas.

The generator also uses `allOf` to attach a field description to a `$ref` property, as OpenAPI 3.0 forbids `$ref` siblings:

```
metadata:
description: metadata provides detailed data about this catalog
allOf:
- $ref: "#/components/schemas/Metadata"
```

## Acceptance criteria:
- Schema pages display properties inherited through local `allOf` $ref entries.
- Inherited required fields are shown as required.
- Properties declared directly on the derived schema override inherited properties with the same name.
- Multi-level allOf inheritance is resolved.
- Cyclic references do not cause infinite recursion or page-generation failure.
- A description-plus-allOf property wrapper remains represented as one property and retains its description.
- Add fixture coverage using a derived catalog schema and at least one described $ref field.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the Go entry point that generates schema reference pages and the existing fixture or generator tests; the issue does not name specific files. Trace how local allOf $ref entries and wrapped described properties are represented, then add fixture coverage for derived catalogs and verify inherited fields, requiredness, overrides, multi-level inheritance, and cyclic references.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, openapi
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.