> For the complete documentation index, see [llms.txt](https://synap.ac/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synap.ac/docs/platform/advanced-features/tags-and-facets.md). # Tags and facets Tags describe what a question is about so Synap can find, select and analyse it consistently. ### The three parts | Concept | Example | What it answers | | ------- | -------------- | --------------------------------------------- | | Tag | Photosynthesis | Which label is attached to the question? | | Facet | Topic | What kind of label is it? | | Tag set | GCSE Biology | Which syllabus or taxonomy does it belong to? | A question can have several Tags—for example **Biology** as its Subject, **Photosynthesis** as its Topic and **Medium** as its Difficulty. These labels can then power question search, learner practice, generated attempts, dynamic Exam selection and performance breakdowns. {% hint style="warning" %} Tags are shared infrastructure. Renaming, deleting or inconsistently applying one can change question pools and reports as well as the Quiz editor. Agree a small taxonomy before tagging a large question bank. {% endhint %} ### How tagging works Think of Tags as structured labels rather than free-form keywords. #### Example A GCSE Biology question about photosynthesis could have: * **Tag set:** GCSE Biology * **Subject:** Biology * **Topic:** Photosynthesis * **Skill:** Data interpretation * **Difficulty:** Medium The Tag supplies the actual value. The Facet tells Synap how to present or analyse that value. The optional Tag set keeps it inside the right curriculum when the portal supports several parallel schemes. #### Where Tags are used | Area | Effect | | ------------------------ | ---------------------------------------------------------------- | | Question editor | Authors classify an individual question | | Quiz and question search | Administrators find relevant questions | | Collections | Learners can generate practice from allowed classifications | | Dynamic Exams | Rules select a requested quantity from eligible tagged questions | | Results and Insights | Performance can be broken down by Tag or Facet | | Imports | A question bank can arrive with taxonomy data already applied | Tags describe the question itself, not merely the Quiz that currently contains it. Reusing the question elsewhere preserves its classification. ### Tags The Tags directory is the central list of question classifications on your portal. ![The Tags directory with search, Facet and Tag set filters](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWXE6hvHQFtER1a1Dm3l5%2Fuploads%2FaOaz5WLJ99JoMAyw5poC%2Ftags-directory.png?alt=media\&token=6d2de52c-3986-4dbb-a087-f1d1f37ca683) #### Directory controls Search by label, filter by Facet or Tag set, choose the sort order and select several rows for supported bulk editing. Each row shows the Synap ID, label, Facet, optional Tag set and whether the Tag is visible to students. #### Tag fields | Field | What it controls | What to consider | | ------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | | Label | The name administrators and, where visible, learners see | Use one spelling and level of detail consistently | | Facet | Whether the label represents Subject, Topic, Skill and so on | The Facet determines where it appears in filtering and analysis | | Tag set | The wider syllabus or taxonomy | Leave blank only when the label is genuinely shared across schemes | | Feedback | Rich-text information associated with the Tag | Use where supported learner feedback should follow this classification | | Visible to students | Allows supported learner pages to expose the Tag | Hiding it from learners does not remove it from admin selection or analysis | The Synap ID remains stable even if the label changes and is useful for imports and integrations. {% hint style="warning" %} Before renaming or deleting a Tag, find where it is used. Existing questions, Collection generation settings, Exam rules and historical reporting can all refer to the same ID. {% endhint %} ### Tag sets Tag sets separate independent curricula or classification schemes that may use similar labels. For example, two qualifications may both have a Tag called **Cell biology** but define its scope differently. Putting those Tags in separate sets lets administrators restrict an Exam or Collection to the intended syllabus. #### Use a Tag set when * the portal supports several qualifications, products or syllabuses; * the same label can have a different meaning in each scheme; * learner practice should expose only one taxonomy; * imports and reporting need to preserve the source classification. Do not create a Tag set for **Topic**, **Skill** or **Difficulty**—those are Facets. A Tag set sits above those dimensions. The Tag sets page lets you add, rename and remove sets. Assign the set when creating or editing each Tag. {% hint style="warning" %} Before removing a Tag set, review the Tags inside it and any Collection or Exam restricted to it. Removing context can broaden, narrow or confuse a question pool even when the individual Tag labels remain familiar. {% endhint %} ### Facets Facets describe the kind of information a Tag represents. They give structure to filtering, learner selection and analysis. | Facet | Use it for | Example | | ---------- | ------------------------------------------- | ------------------- | | Subject | A broad discipline | Biology | | Topic | A major area within the subject or syllabus | Cell biology | | Subtopic | A narrower area | Cell membranes | | Skill | The capability being assessed | Data interpretation | | Difficulty | Your organisation’s difficulty band | Medium | | Context | A scenario or other grouping | Laboratory safety | Facets do not automatically create a hierarchy. Synap does not infer that one Subtopic belongs beneath one particular Topic merely from the two Facet values. Authors must apply the appropriate Tags, and your naming rules must preserve any intended relationship. #### Learner-facing use When Tags are visible to students, a Collection can expose supported Facets as choices for generated practice. Decide which classifications will make sense to a learner without administrator context. A meaningful Topic or Difficulty choice is helpful; internal migration codes usually are not. {% hint style="info" %} Choose the same Facet for the same kind of classification. Moving similar labels between Topic, Subtopic and Context fragments filters and performance breakdowns. {% endhint %} ### Applying tags to questions Apply Tags from the **Tags** tab of the question editor. The Tags become part of the question and remain attached when that question is reused in another Quiz. #### In the question editor 1. Open the question and select **Tags**. 2. Search or browse the available classifications. 3. Add the Tags that accurately describe this question. 4. Check that each Tag belongs to the intended Facet and Tag set. 5. Save the question. Apply classifications that will support an actual decision: finding the question, generating a balanced paper, offering learner practice or interpreting performance. Adding every remotely related label makes selection rules less predictable. #### Bulk and import workflows Comma-separated values (CSV) import can classify many questions as they are created or updated. Supported bulk tools can update selected questions, and exports can help audit a bank. Use stable Tag IDs where the workflow supports them; matching only on a human-readable label is risky when several Tag sets contain similar names. {% hint style="warning" %} After a large tagging change, test the downstream features that rely on it. A question can be perfectly valid in the editor yet become unexpectedly eligible—or ineligible—for a dynamic Exam. {% endhint %} ### Dynamic exam selection Dynamic Exam selection builds a paper from eligible questions instead of using one permanently fixed list. #### How a rule works A rule combines Tag criteria with a requested number of questions. For example, an Exam could request ten **Topic: Cell biology** questions and five **Skill: Data interpretation** questions. Synap evaluates the current question bank when generating an Attempt. | Check | Why it matters to an administrator | | --------------------------- | -------------------------------------------------------------------------- | | Eligible question count | A rule cannot supply more questions than its matching pool contains | | Overlap | One question may match several criteria, depending on the selection design | | Untagged questions | They will not satisfy rules requiring a classification | | Tag set | The same-looking label may belong to a different syllabus | | Visibility and availability | A matching question must still be usable by the delivery workflow | | Bank changes | Editing questions or Tags can change future generated papers | Dynamic selection does not reserve a fixed set of questions when the rule is authored. This is useful because the bank can evolve, but it means a previously successful setup should be tested again after substantial question or taxonomy changes. {% hint style="warning" %} Generate several previews, not just one. Confirm that each paper has the intended coverage and that every rule has a comfortable pool beyond the minimum required count. {% endhint %} ### Analytics and reporting Tag analysis groups question performance by the classifications applied to those questions. Depending on the Results or Insights page, you can use Tag and Facet breakdowns to compare topics, skills, difficulty bands or other configured dimensions. This can reveal that a learner or cohort performs differently across parts of the syllabus. #### Read the result in context | Question to ask | Why | | ---------------------------------------------------- | ------------------------------------------------------------------------- | | How many questions contributed? | A small sample is unstable | | Were the questions tagged consistently? | Missing or incorrect Tags distort the group | | Did the questions have similar marks and difficulty? | A lower percentage may reflect question design rather than mastery | | Which Tag set was used? | Similar labels can represent different curricula | | Is this current or historical data? | Later Tag edits do not necessarily change the meaning of an older Attempt | Use a Tag result as a route into the evidence, then inspect the contributing questions and Attempts before making a high-stakes decision about a learner or programme. {% hint style="info" %} Taxonomy quality is reporting quality. A smaller set of consistently applied Tags usually produces more trustworthy insights than a large catalogue used unevenly. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://synap.ac/docs/platform/advanced-features/tags-and-facets.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.