[{"id":"openapiadvanced-001","courseId":"openapi-advanced","domain":"document-structure","topic":"Entry document resolves references","prompt":"An OpenAPI description is split across two files. openapi.yaml is the entry document, and a $ref in it points at a schema in shared.yaml. The tool has read only the first half of shared.yaml. What should it do?","hint":"Think about when a missing target is actually missing.","explain":"A description can span several files, and a reference may point into any of them. Whether a target exists depends on all candidate files, not just the one holding the reference.","source":"https://spec.openapis.org/oas/latest.html","interaction":{"type":"single"},"options":[{"id":"a","text":"Keep parsing the rest of shared.yaml before deciding the reference is unresolvable","why":"Every document must be fully parsed to find reference targets, and a reference may not be declared unresolvable before all candidates are read."},{"id":"b","text":"Report the reference as broken now, since the target is not in the part already read","whyNot":"The target may sit in the unread part, so declaring it broken early is not allowed."},{"id":"c","text":"Resolve the reference only against the entry document, since that is where parsing starts","whyNot":"Reference targets can be defined in any document of the description, not just the entry document."},{"id":"d","text":"Drop the reference and validate the schema without it, since the target is missing","whyNot":"Dropping the reference before the full parse is the same mistake as declaring it broken early."}],"answer":"a","explanation":"Every document in a multi-document description must be fully parsed to locate reference targets, and a reference cannot be treated as unresolvable before all candidate documents are parsed.","concept":"Every document in a multi-document description must be fully parsed to locate reference targets, and a reference cannot be treated as unresolvable before all candidate documents are parsed.","rev":1,"updatedAt":"2026-10-26","kind":"scenario","takeaways":["A dangling reference may just be a target in a file you have not finished reading."]},{"id":"openapiadvanced-002","courseId":"openapi-advanced","domain":"document-structure","topic":"Parsing fragments in isolation","prompt":"In OpenAPI 3.1 and later, the result of parsing a referenced fragment in isolation, without the rest of its document, is undefined.","hint":"Consider what a fragment loses when you cut it out of its file.","explain":"A referenced piece can depend on settings elsewhere in its file, such as ones that move the base for relative addresses. Reading the piece alone can miss context it needs.","source":"https://spec.openapis.org/oas/latest.html","interaction":{"type":"true-false"},"options":[{"id":"a","text":"True","why":"From 3.1 on, the spec says the result of isolated fragment parsing is undefined and likely to contradict its requirements."},{"id":"b","text":"False","whyNot":"The spec defines no result for isolated parsing, because keywords outside the fragment can change what it means."}],"answer":"a","explanation":"From OpenAPI 3.1 on, parsing a referenced fragment in isolation has an undefined result, and depending on that result is not recommended.","concept":"From OpenAPI 3.1 on, parsing a referenced fragment in isolation has an undefined result, and depending on that result is not recommended.","rev":1,"updatedAt":"2026-10-26","kind":"scenario","takeaways":["Keywords outside a fragment can change how the fragment's references resolve."]},{"id":"openapiadvanced-003","courseId":"openapi-advanced","domain":"document-structure","topic":"Tag parent must exist","prompt":"A description's top-level tags list declares 'billing' twice. One operation uses the tag 'reports', which the list never declares. Which TWO statements about this are correct?","hint":"Check what the spec allows for repeated names and for tags left undeclared.","explain":"A description can attach labels to operations and declare them once in a shared list. The rules cover how often each label may appear in that list and whether every label used must be listed.","source":"https://spec.openapis.org/oas/latest.html#tag-object","interaction":{"type":"multiple","tellCount":true},"options":[{"id":"a","text":"The duplicate 'billing' entry breaks the rule that each tag name in the list is unique","why":"Each tag name in the list must be unique, so a repeated name is not allowed."},{"id":"b","text":"The operation may keep using 'reports' even though the list does not declare it","why":"Not every tag an operation uses has to be declared, and undeclared tags are allowed."},{"id":"c","text":"The description is invalid, because every tag an operation uses must be declared in the list","whyNot":"The spec says not all used tags must be declared, so requiring it is a misconception."},{"id":"d","text":"Two tags with the same name are fine when their descriptions differ","whyNot":"Uniqueness is about the name alone, so different descriptions do not make a duplicate legal."},{"id":"e","text":"Tools must show tags in the order the list gives them","whyNot":"The list order can be used by parsing tools, but that use is optional, not required."},{"id":"f","text":"A tool must drop an operation's undeclared tag when it parses the file","whyNot":"Undeclared tags may be organized by the tool's own logic, not removed."}],"answer":"ab","explanation":"Each tag name in the top-level tags list must be unique, but a tag an operation uses need not be declared in that list.","concept":"Each tag name in the top-level tags list must be unique, but a tag an operation uses need not be declared in that list.","rev":1,"updatedAt":"2026-10-26","kind":"scenario","takeaways":["Tag names must be unique in the list; an operation may use a tag the list never declares."]},{"id":"openapiadvanced-004","courseId":"openapi-advanced","domain":"document-structure","topic":"Circular tag parents","prompt":"Document A references a schema in document B. B sets $self to https://example.com/api/shared/foo but was downloaded from a staging host. For interoperability, which URI should A's reference use?","hint":"Think about which address a document calls itself.","explain":"A document can declare its own canonical address, separate from where it is hosted or stored. Interoperable references are meant to name that address, so one reference works across deployments.","source":"https://spec.openapis.org/oas/latest.html#tag-object","interaction":{"type":"single"},"options":[{"id":"a","text":"https://example.com/api/shared/foo, the target's $self value","why":"When $self is present, references must use the target document's $self URI for interoperability."},{"id":"b","text":"The staging address where the file was downloaded","whyNot":"Some tools may support retrieval URIs, but relying on them is not interoperable and is not recommended."},{"id":"c","text":"A relative file path from document A's folder to document B","whyNot":"File paths depend on the local layout, so they are not the identity the spec names for references."},{"id":"d","text":"Any address that serves the same bytes as document B","whyNot":"Identical copies can live anywhere, and the spec names the $self URI as the interoperable target."}],"answer":"a","explanation":"When a document has a $self field, references to it must use its $self URI for interoperability; using the retrieval URI is not interoperable and not recommended.","concept":"When a document has a $self field, references to it must use its $self URI for interoperability; using the retrieval URI is not interoperable and not recommended.","rev":1,"updatedAt":"2026-10-26","kind":"scenario","takeaways":["Point references at a document's $self URI, not at wherever a copy happens to be fetched from."]},{"id":"openapiadvanced-005","courseId":"openapi-advanced","domain":"document-structure","topic":"Tag kind is free text","prompt":"In OpenAPI 3.2, the kind field of a tag must hold one of the values listed in the Tag Kind Registry.","hint":"Compare what a registry is with what the field is allowed to hold.","explain":"Some fields come with a registry of commonly used values. A registry can guide authors without limiting the field, so how a field is defined decides whether its values are restricted.","source":"https://learn.openapis.org/specification/tags.html","interaction":{"type":"true-false"},"options":[{"id":"a","text":"True","whyNot":"The registry lists values commonly used and supported by tooling, but the field accepts other text too."},{"id":"b","text":"False","why":"The kind field is free text: the registry is a guide, and authors may use values outside it."}],"answer":"b","explanation":"The tag kind field is free text: a registry lists commonly used values, but authors may use other values.","concept":"The tag kind field is free text: a registry lists commonly used values, but authors may use other values.","rev":1,"updatedAt":"2026-10-26","kind":"scenario","takeaways":["A registry of common values is guidance for tooling, not a list the field is limited to."]}]