Ontology Extensions¶

This directory contains extensions to the base HSRS ontology. Extensions are added through a controlled review process.

Extension Protocol¶

1. Proposal¶

Before adding new concepts, create a proposal with: - Concept name (Hebrew and transliterated) - Source citation (must have at least one makor) - Sort membership (which sort does this belong to?) - Relationship to existing concepts - Example usage

2. Schema Definition¶

Define the new concept with proper sort and constraints:

% Extension: [concept_name]
% Source: [citation]
% Added: [date]
% Reviewer: [name]

% Sort membership
new_concept(X) :- ...

% Constraints
:- new_concept(X), violates_constraint(X).

3. Consistency Check¶

Run clingo to verify no conflicts:

clingo mistaber/ontology/schema/*.lp mistaber/ontology/base/*.lp mistaber/ontology/extensions/new_extension.lp --warn=none 0

Expected: SATISFIABLE

4. Human Review¶

All extensions require human review before merging: - Verify source citations are accurate - Verify halachic accuracy of encoding - Verify no conflicts with existing rules

5. Version Tracking¶

Each extension file must include: - Creation date - Author/reviewer - Source citations - Change log

Naming Conventions¶

Files: snake_case.lp
Predicates: snake_case/N
Constants: snake_case
Comments: English with Hebrew terms in parentheses

Directory Structure¶

extensions/
├── README.md           # This file
├── custom_foods.lp     # Domain-specific food classifications
├── local_minhagim.lp   # Local customs extensions
└── ...

Example Extension¶

% Extension: kitniyot
% Source: Shulchan Arukh OC 453:1
% Added: 2026-01-20
% Reviewer: Rabbi X

% Kitniyot category (Ashkenazi custom)
food_category(kitniyot).

% Kitniyot items
kitniyot_item(rice).
kitniyot_item(corn).
kitniyot_item(beans).

% Forbidden on Pesach for Ashkenazim (minhag level)
forbidden(W, achiila, F, ctx_pesach) :-
    active_in_world(r_kitniyot, W),
    food(F),
    kitniyot_item(FoodName),
    food_name(F, FoodName).

% Rule metadata
rule(r_kitniyot).
scope(r_kitniyot, ashkenaz).
makor(r_kitniyot, sa("oc:453:1")).
madrega(r_kitniyot, minhag).

Best Practices¶

1. Start with Schema Sorts¶

Always check which sort your concept belongs to: - entity/1 - Physical things (food, vessel, person, animal) - action/1 - Actions (eating, cooking, benefit) - issur_type/1 - Prohibition types - context/1 - Halachic contexts (shabbat, pesach, etc.) - madrega/1 - Normative levels (d_oraita, d_rabanan, minhag, chumra) - rule/1 - Halachic rules - world/1 - Possible worlds (for modal reasoning)

See mistaber/ontology/schema/sorts.lp for the full list.

2. Use Proper Citation Format¶

Citations should follow standardized formats: - Shulchan Arukh: sa("section:chapter:paragraph") e.g., sa("oc:453:1") - Mishnah: mishnah("tractate:chapter:mishnah") e.g., mishnah("berachot:1:1") - Talmud: gemara("tractate:page:side") e.g., gemara("berachot:2a") - Rambam: rambam("book:chapter:halacha") e.g., rambam("hilchot_shabbat:1:1")

3. Respect the Disjointness Rules¶

The schema enforces disjointness between core sorts. Your extensions must not violate these: - An entity cannot be an action - An issur_type cannot be a context - A madrega cannot be a rule

See mistaber/ontology/schema/disjointness.lp for all disjointness constraints.

4. Document Your Reasoning¶

Include comments explaining: - Why this extension is needed - How it relates to existing concepts - Any edge cases or exceptions - References to sources for verification

5. Test Incrementally¶

Test your extension in stages: 1. Test schema consistency alone 2. Test with base ontology 3. Test with sample queries 4. Test edge cases

Common Extension Patterns¶

Pattern 1: Adding New Food Items¶

% Extension: specific_food_item
% Source: [citation]
% Added: [date]

% Declare the food
food(quinoa).
food_name(quinoa, quinoa).

% Classify if needed
grain_like(quinoa).  % If this is relevant for existing rules

Pattern 2: Adding Local Minhagim¶

% Extension: community_custom
% Source: Local community authority
% Added: [date]
% Scope: Specific community

% Define the rule
rule(r_community_custom).
scope(r_community_custom, community_name).
madrega(r_community_custom, minhag).
makor(r_community_custom, local_authority).

% Define when it applies
forbidden(W, Action, Entity, Context) :-
    active_in_world(r_community_custom, W),
    % ... specific conditions ...

Pattern 3: Extending Status Hierarchies¶

% Extension: new_status_level
% Source: [citation]
% Added: [date]

% Declare the status
status(new_status).

% Define its relationships
status_stricter(existing_status, new_status).

Pattern 4: Adding Derived Rules¶

% Extension: derived_prohibition
% Source: [citation]
% Added: [date]

% Define the derived rule
rule(r_derived).
madrega(r_derived, d_rabanan).
makor(r_derived, source_citation).

% Define the derivation logic
forbidden(W, ActionType, Entity, Context) :-
    active_in_world(r_derived, W),
    base_condition(Entity),
    derived_condition(Context),
    % ... additional logic ...

Integration with the Compiler¶

Extensions are compiled alongside the base ontology. To use extensions in your queries:

Place your extension file in mistaber/ontology/extensions/
The compiler automatically includes all .lp files in this directory
Extensions are loaded after schema and base ontology
Extensions can reference all schema sorts and base predicates

Troubleshooting¶

UNSATISFIABLE Error¶

If clingo reports UNSATISFIABLE: 1. Check for conflicting constraints 2. Verify all referenced predicates exist 3. Check disjointness violations 4. Review sort membership declarations

Unexpected Results¶

If queries produce unexpected results: 1. Test the extension in isolation 2. Verify rule activation conditions 3. Check world/context filtering 4. Review madrega hierarchy implications

Performance Issues¶

If queries become slow: 1. Minimize recursive rules 2. Use grounded predicates where possible 3. Add constraints to reduce search space 4. Consider splitting complex extensions

Questions?¶

For questions about extensions: 1. Review existing base files for patterns 2. Consult the schema documentation 3. Test with minimal examples 4. Seek human review before committing