We introduce the Simple Argument Description Notation (SADN), a declarative language for describing arguments. SADN is built upon the existing, document-oriented, SADFace argument description format and is used to interactively and declaratively construct argument descriptions. A worked illustrated example is presented in which an argument model is constructed through the application of SADN. The Simple Argument Description Notation (SADN1) is a language for describing arguments in an incremental, line-oriented declarative fashion. SADN is built upon the Simple Argument Description Format (SADFace) [1] which provides a core ontology of argumentative concepts and an implemented library for constructing and manipulating SADFace documents using either Python3 or Javascript. The core idea behind SADN is that the SADFace document is interpreted as a dynamic model of the argument at issue. The user makes line oriented declarations such that each declaration modifies the SADFace argument description, leaving a complete, coherent and consistent SADFace model at each stage. This builds upon prior work on declarative dialogue description languages [2]. The user might start with an empty model, or load an existing model for further manipulation and then execute SADN declarations where each declaration is a command in the Read-Evaluate-Print Loop (REPL) and each line of the REPL represents a distinct, indexed, temporal timestep in the life of the argument model. A key conceptual diference between SADFace and SADN lies in the idea that SADFace is a single static object, a multi-line document, whereas SADN extends this idea to interpret the SADFace document as a dynamic model that exists wholly and fully formed at each time step as indexed by REPL lines. One way of interpreting this relationship is as a single SADFace document representing the state of the SADN dialogue, or alternatively, that SADN generates a directed graph of succcessive SADFace documents, each representing the state of the world after a SADN declaration. SADN and SADFace should therefore be considered as isomorphic modes of interaction with the same underlying argumentative model. One motivation for this work is to better capture the dynamic process that relates dialogical dynamics to a argumentative structure. After any given utterance within a dialogue, there exists a corresponding argumentative structure that models the state of the arguments, made by the participants, for and against the issue that is at stake. This initial version of SADN focusses solely upon capturing the dynamic construction aspect of the argument model and leaves the next stage of capturing dialogue dynamics to future work. In the remainder of this paper we begin by briefly discussing related work, cover some background material, in the form of a brief introduction to the SADFace format and library implementation upon which SADN builds, then introduce an annotated presentation of the SADN commands. We present
an example of a SADN session and some discussion of supporting tooling and applications before concluding with a discussion of future directions.
Two archetypal prior approaches to declarative argument descriptions include DeLP [
SADN builds directly upon the core concepts defined within SADFace, as an argument description format, whilst also utilising the argumentative model built into the SADFace library implementation. Therefore it is sensible to briefly describe those features of SADFace most pertinent to SADN.
SADFace is a Javascript Object Notation (JSON) [
Arguments are made up from statements (or strings if you’re a programmer) that capture either a “claim” or supporting information for that claim. In SADFace these statements are called “Argument Atoms”, or just “atoms”. A simple argument is a collection of such atoms that are linked together. For a simple, single, argument we generally say that one of the atoms is a conclusion, and the other atoms are premises supporting that conclusion. The exact way that premises support a conclusion is defined by an argumentation scheme. An argumentation scheme captures a stereotypical pattern of argumentative reasoning or inference, so diferent arguments can be categorised into diferent types. A rough rule of thumb within SADFace is to consider every individual argument is being an instance of an argumentation scheme.
The underlying model of SADFace is the Mathematical Graph [
Atoms cannot be linked directly to each other. They must be linked via a Scheme node. This is in line
with the underlying model of the Argument Interchange Format (AIF) [
Figure 1 shows a fragment of JSON that presents an abbreviated illustration of an argument described in SADFace. Note that only one example of each element is included and the remainder of the full analysis has been elided for brevity and replaced with ‘. . . ’.
This description yields a visualisation, using the MonkeyPuzzle argument diagramming layout
method [
SADN is designed primarily to be used in a terminal or REPL, or else piped between command line applications. The result of any given SADN expression is an argument structure that is a syntactically valid5 SADFace model.
The following is an annotated list of the core SADN commands for declarative SADFace argument model construction and manipulation. Each command is depicted in bold and the annotations in regular text. Some elements are depicted using the following form $UPPERCASE to indicate variables or elements that are not SADN commands. Such elements includes identifiers, and text string values associated with SADFace keys. Additionally, the vertical bar ‘|’ is used to indicate a choice between alternatives, e.g.‘a | b’, meaning ‘a or b’. atom(id:$ID, text:$TEXT) – Add a new atom node. $CONTENT is an optional quoted string containing the textual content of the atom. If the atom command is executed with an existing $ID and a new text $TEXT then this will cause the existing atom node’s text value to be updated with the new $TEXT string. scheme(id:$ID, name:$TEXT) – Add a new scheme node. $TEXT is an optional quoted string containing the name of the associated argumentation scheme. If no $TEXT is supplied then a generic “support” name will be used. If the scheme command is executed with an existing $ID and a new name $TEXT then the existing scheme node will be updated with the new name. Commentary: The atom and scheme commands are grouped together because they have the same basic form and have similar efects. Each command can be run without arguments to yield, respectively, the introduction of a single SADFace atom or scheme node with a generic name/content and automatically generated ID into the SADFace model. support(scheme:$ID, conclusion:$ID, premise:$ID, ...) – Create a new supportive relationship between the existing nodes identified by the conclusion and premise IDs. The support command allows an arbitrary number of premise IDs to be supplied. If no scheme ID is supplied then a new generic “support” node is created . attack(source:$ID, target:$ID) – Create a new attack relationship between the supplied nodes identified by the source and target $IDs. Attack is a uni-directional conflict from one argument that is directed towards another argument. A new conflict node of type attack is created as a result.
disagree($ID, $ID, ...) – Create a new disagreement relationship between the nodes identified by the supplied $IDs. Disagree is a bi-directional conflict between two or more arguments A new conflict node of type disagreement is created as a result.
Commentary: The support, attack, and disagree commands are grouped together because they work similarly, used to create relationships between nodes, but have distinct individual semantic interpretations in terms of how they afect the SADFace model. argument(scheme:$TEXT, conclusion:$ID | text:$CONTENT, premise:$ID | text:$CONTENT, ...) – Builds a complete argument structure in a single command. If no name $TEXT is supplied then a generic ‘support’ label will be added to the scheme. The remainder of the arguments are a comma separated list of arbitrary length of either $IDs referring to pre-existing nodes or double-quoted $TEXT strings which cause new atoms to be created. The first ID supplied will be interpreted as the concluding node, all other IDs will be interpreted as premises.
Commentary: The argument command is syntactic sugar to enable an entire argument structure to be constructed in one declaration and in a fairly ad-hoc manner using a mixture of IDs for pre-existing atoms and content for atoms to be created during the execution of this command. The usefulness of the argument() command for rapidly introducing entire argument structures comes at the expense of some additional complexity. remove(id:$ID, ...) – Remove the element identified by $ID from the model. This also removes any dependent elements within the SADFace model such as edges if the removed element is either the source or target of the edge.The remove operation is idempotent and repeated use on the same $ID will make no further change to the model. If no $ID is supplied the remove has no efect on the model.
Commentary: The remove command is unique in that it is the only command that will remove specified elements from the SADFace model metadata(id:$ID, namespace:$TEXT, $KEY:$TEXT) – Used to add a metadata entry to the identified namespace of the SADFace element identified by $ID. Elements that can support metadata blocks are the model’s global metadata block, individual nodes, and individual resources. If the $KEY already exists then the $TEXT updates itand if the $KEY doesn’t exist then that key is created. Commentary: Name-spaced metadata at defined places in the model is a key to SADFace’s claim to extensibility. The metadata command enables metadata to be captured as required during declarative SADN REPL sessions. atoms - Lists the atom nodes in the current SADFace model. schemes - Lists the scheme nodes in the current SADFace model. conflicts - Lists the conflict nodes, in the current SADFace model which includes both attacks and disagreements. edges - Lists the edges in the current SADFace model.
Commentary: These are used primarily to see what nodes and edges are in the current model and to
access the mapping from UUID to local alias. Because the elements that make up a SADFace model
can be spread over an extended SADN REPL session and can be dificult to keep track of, it is useful
to be able to access, list, group, and display the elements of the model so that they can be more easily
manipulated. These commands work in concert with the print and prettyprint commands to support
interactive manipulation of the SADFace model.
export(type:$TYPE) – SADFace supports exporting the SADFace model into a range of other
textbased forms, for example, Dot and Cytoscape[
Commentary: This final grouping of commands are all utility functions for manipulating, importing, exporting, and working with SADN but don’t directly modify the SADFace model.
Notice that some commands are complex and take one or more arguments which are embraced in parenthesis whereas other simple commands include neither arguments nor parenthesis. Of the commands that take arguments, notice that the argument lists are explicitly structured as comma separated lists of key:value pairs.
In any command that consumes an $ID (except for the remove command, if no $ID is supplied then a new UUID and local UUID Alias will be created that are unique to the SADFace elements being created. If the same command is called without specified $IDs then that command will complete each time with new elements created containing generated IDs.
Where commands can support more complex relationship structures, such as in the support, attack, and disagree relationships, the first $ID is interpreted as the head element, and any remaining $ID elements are interpreted as the tail element(s). For example, support(id:a1, id:a2, id:a3) yields an argument where atom a1 is the conclusion, and the remaining atoms a2 and a3 are premises, all of which are linked via a ‘support’ scheme node.
One challenging user experience issue within SADN is the use of long, and quite unwieldy, universally unique identifiers (UUIDs) which are core to how SADFace creates globally unique argument instances. See Figure 1 for an illustration of a range of UUIDs associated with the various “id” keys in SADFace. Manipulating UUIDs within the command line involves either error prone typing or else copy-pasting. SADN introduces transparent local aliasing as syntactic sugar to make it easer to use SADN without manipulating otherwise unwieldy UUIDS in the terminal and thus to improve the user experience. UUIDs are replaced locally with short monotonically increasing unique identifiers whose basic form runs together a lowercase letter code indicating node type and an integer (starting at 1 and incrementing monotonically as necessary). For example, an Atom, having textual content, associated metadata, and a unique ID might be depicted as follows in SADFace: {
But when instantiated in SADN, the atom identified by the UUID “ae3f0c7f-9f69-4cab-9db33b9c46f56e09” might be referred to using the term a1 for Atom #1 within that specific SADN session. Each SADFace element is treated similarly, assigned a letter code based upon type and a numeric identifier based upon when the element was expressed during the current SADN session. Available letter codes include a for Atom, s for scheme, c for conflicts, and e for edges. Internally SADN session IDs are mapped to original UUIDs using a lookup table. If a SADFace document is read into a SADN session then the original UUIDs are maintained in the lookup table and SADN sessions IDs are generated incrementally as the document is processed. If a SADN session starts with an empty document, then session IDs are generated incrementally as needed as the session progresses, UUIDs are also generated for each element so that all SADFace models, generated through SADN, can be serialised to universally valid SADFace documents.
A limited prototype of SADN is included in the current SADFace release. To access this, you will need a working Python 3 installation. SADFace can then be installed using pip, i.e. pip install sadface6. From there, the SADFace REPL can be initiated using python3 -m sadface -i7. A SADFace configuration file can be passed into the invocation of the SADN REPL which will cause the new SADFace model to be built using configuration information, such as analyst email and name, from the file. This is achieved using the following command python -m sadface -c test.cfg -i where the configuration is stored in the test.cfg file 8
In this example, we’ll recreate the example argument from the MonkeyPuzzle demo. We’ll show the commands in the REPL, and where appropriate, the SADFace model and MonkeyPuzzle visualisation. Upon starting the SADFace REPL without a configuration file or any other inputs you will be presented with the following prompt at which you can type SADN commands: The SADFace REPL. Type ’help’ or ’help <command>’ for assistance > The associated SADFace model is empty, containing neither nodes nor edges or resources and the core metadata will contain default information for the analyst name and email address keys, current timestamps for the created and edited keys, a universally unique identifier for the ID key, and the semantic version number for the version of SADFace associated with the model. By executing the pp command, the abbreviated version of the prettyprint command from the list introduced in section 4.1, the current model will be displayed as follows: The SADFace REPL. Type ’help’ or ’help <command>’ for assistance > pp { "edges": [], "metadata": { "core": { "analyst_email": "Default Analyst Email", "analyst_name": "Default Analyst Name", "created": "2025-10-29T17:53:05", "edited": "2025-10-29T17:53:30", "id": "4ab333ea-a003-4631-afa7-5f20806a8497", "version": "0.5.3.2" } 6It is best practise to install the SADFace tooling into a virtual environment 7NB. The invocation of Python might difer across platforms and installations. 8A valid starter configuration file can be found in the SADFace repo at SADFace/tools/python/etc/defaults.cfg.
We can now add some nodes and edges to the model. Let’s start by adding the nodes for the initial sub-argument, then we’ll use the print command and the list("atoms") commands to show the efect on the model: > atom(text:"Every person is going to die") > atom(text:"You are a person") > atom(text:"You are going to die") > print {"edges":[],"metadata":{"core":{"analyst_email":"Default Analyst Email","analyst_name":" Default Analsyst Name","created":"2025-10-29T17:53:05","edited":"2025-10-29T17 :53:30","id":"4ab333ea-a003-4631-afa7-5f20806a8497","version":"0.5.3.2"}},"nodes ":[{"id":"a03ea3f2-70f2-42ed-962c-f15367e79de7","type":"atom","text":"Every person is going to die","sources":[],"metadata":{}},{"id":"6e73e177-4e62-45e4-bd0d-62 d72891c339","type":"atom","text":"You are a person","sources":[],"metadata":{}},{"id ":"bba487d5-029a-4a1b-ae79-ad69c769382a","type":"atom","text":"You are going to die ","sources":[],"metadata":{}}],"resources":[]} >atoms ["a1":{"id":"a03ea3f2-70f2-42ed-962c-f15367e79de7", "text":"Every person is going to die "}, "a2":{"id":"6e73e177-4e62-45e4-bd0d-62d72891c339", "text":"You are a person"}, " a3":{"id":"bba487d5-029a-4a1b-ae79-ad69c769382a", "text":"You are going to die"}] Now we’ll add the edges to join the atoms together into an argumentative structure. We’ll use the support command to do this. We won’t specify a scheme ID as we haven’t created a scheme node yet. Instead we’ll accept the scheme node generation as a side efect of creating the support structure. So we’ll only identify the conclusion and premises, using the local atom IDs output from the list command above and applying conclusion and premise labels. We’ll then use the schemes command to see the list of scheme nodes, now that one has been created, and finish by displaying the current model using print once more: > support(conclusion:"a3", premise:"a1", premise:"a2") >schemes ["s1":{"id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999", "name":"Support"}] > print {"edges":[{"id":"81d94ca5-4cb1-4c4d-8486-708d45b45c4e","source_id":"a03ea3f2-70f2-42ed -962c-f15367e79de7","target_id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999"},{"id":"233 af9c1-ba7e-4967-9c32-3025ac65ee67","source_id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999 ","target_id":"bba487d5-029a-4a1b-ae79-ad69c769382a"},{"id":"75c9ef27-7ba4-4cbf-8fde -e957698f472b","source_id":"6e73e177-4e62-45e4-bd0d-62d72891c339","target_id":" b3b0e13a-8b8b-4e2a-9544-5ab401e58999"}],"metadata":{"core":{"analyst_email":"Default
Analyst Email","analyst_name":"Default Analsyst Name","created":"2025-10-29T17 :53:05","edited":"2025-10-29T18:02:25","id":"4ab333ea-a003-4631-afa7-5f20806a8497"," version":"0.5.3.2"}},"nodes":[{"id":"a03ea3f2-70f2-42ed-962c-f15367e79de7","type":" atom","text":"Every person is going to die","sources":[],"metadata":{}},{"id":"6 e73e177-4e62-45e4-bd0d-62d72891c339","type":"atom","text":"You are a person"," sources":[],"metadata":{}},{"id":"bba487d5-029a-4a1b-ae79-ad69c769382a","type":"atom ","text":"You are going to die","sources":[],"metadata":{}},{"id":"b3b0e13a-8b8b-4 e2a-9544-5ab401e58999","type":"scheme","name":"Support"}],"resources":[]} Now is an opportune moment to view the visualisation of the argument structure constructed so far. We’ll use MonkeyPuzzle to do this using the SADFace model from the REPL. The result is shown in Figure 3
Finally we’ll complete the argument map from the MonkeyPuzzle demonstration but this time we’ll use the argument() command to combine a number of simpler commands into a single declaration.
This combines supplying a mixture of local IDs from existing atoms, and strings to create new nodes or reuse existing nodes, as required within the same command to build an argument structure in a single declaration. Whilst such syntactic sugar is not necessary, and the same efect can be built from primitive SADN commands, this approach does reduce the number of commands necessary to achieve the same efect. > argument(conclusion: "You should treasure every moment", premise: "a3", premise: "If you are going to die then you should treasure every moment") > atoms ["a1":{"id":"a03ea3f2-70f2-42ed-962c-f15367e79de7", "text":"Every person is going to die "}, "a2":{"id":"6e73e177-4e62-45e4-bd0d-62d72891c339", "text":"You are a person"}, " a3":{"id":"bba487d5-029a-4a1b-ae79-ad69c769382a", "text":"You are going to die"}, " a4":{"id":"3b666117-d50c-4de8-b2ed-29f6ae98f10a", "text":"You should treasure every moment"}, "a5":{"id":"df8e97d1-b2d6-4768-bd82-ea91a8820313", "text":"If you are going to die then you should treasure every moment"}] > schemes ["s1":{"id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999", "name":"Support"}, "s2":{"id":"42 ba2acc-d8d2-4d8f-ae93-c7f8c383b4bb", "name":"Support"}] > print {"edges":[{"id":"81d94ca5-4cb1-4c4d-8486-708d45b45c4e","source_id":"a03ea3f2-70f2-42ed -962c-f15367e79de7","target_id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999"},{"id":"233 af9c1-ba7e-4967-9c32-3025ac65ee67","source_id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999 ","target_id":"bba487d5-029a-4a1b-ae79-ad69c769382a"},{"id":"75c9ef27-7ba4-4cbf-8fde -e957698f472b","source_id":"6e73e177-4e62-45e4-bd0d-62d72891c339","target_id":" b3b0e13a-8b8b-4e2a-9544-5ab401e58999"},{"id":"e21ddbcc-ce50-4ce9-839e-5f8f5e2d5af4 ","source_id":"df8e97d1-b2d6-4768-bd82-ea91a8820313","target_id":"42ba2acc-d8d2-4d8f -ae93-c7f8c383b4bb"},{"id":"adbc1971-5334-4daa-86bb-d7d706a3b8cc","source_id":"42 ba2acc-d8d2-4d8f-ae93-c7f8c383b4bb","target_id":"3b666117-d50c-4de8-b2ed-29 f6ae98f10a"},{"id":"00695abb-e8aa-4f08-9af8-7fca55d53270","source_id":"bba487d5-029a -4a1b-ae79-ad69c769382a","target_id":"42ba2acc-d8d2-4d8f-ae93-c7f8c383b4bb"}]," metadata":{"core":{"analyst_email":"Default Analyst Email","analyst_name":"Default Analsyst Name","created":"2025-10-29T17:53:05","edited":"2025-10-29T18:50:13","id ":"4ab333ea-a003-4631-afa7-5f20806a8497","version":"0.5.3.2"}},"nodes":[{"id":" a03ea3f2-70f2-42ed-962c-f15367e79de7","type":"atom","text":"Every person is going to die","sources":[],"metadata":{}},{"id":"6e73e177-4e62-45e4-bd0d-62d72891c339","type ":"atom","text":"You are a person","sources":[],"metadata":{}},{"id":"bba487d5-029a -4a1b-ae79-ad69c769382a","type":"atom","text":"You are going to die","sources":[]," metadata":{}},{"id":"b3b0e13a-8b8b-4e2a-9544-5ab401e58999","type":"scheme","name":" Support"},{"id":"df8e97d1-b2d6-4768-bd82-ea91a8820313","type":"atom","text":"If you are going to die then you should treasure every moment","sources":[],"metadata ":{}},{"id":"3b666117-d50c-4de8-b2ed-29f6ae98f10a","type":"atom","text":"You should treasure every moment","sources":[],"metadata":{}},{"id":"42ba2acc-d8d2-4d8f-ae93c7f8c383b4bb","type":"scheme","name":"Support"}],"resources":[]}
The final Monkeypuzzle visualisation of the argument constructed in the SADN REPL can be seen in Figure 4
There are a number of immediate applications for SADN. The primary application, in line with the earlier
example, is as an interactive declarative language, with supporting utilities, for constructing argument
models without needing to resort to manual argument diagramming software like MonkeyPuzzle. This
approach has been demonstrated in the worked example in section 5. MonkeyPuzzle and SADFace are
not the only target applications however, and the core commands could easily be reused to work with
other argument models and descriptions. One easy route towards this is through extending the export
functionality of SADFace to account for new models as they become available. A second application of
SADN is within an interactive argument evaluation context. In this application, SADN commands are
used to build a model that is then piped through additional tools to evaluate the argument on the fly,
for example, piping the state of the SADFace model from the SADN REPL through to a tool like TOAST
in order to evaluate the constructed model under the ASPIC+ theory. On design goal of SADN was to
produce a declarative language that could be used interactively when working with arguments, that
covers the core concepts of argumentative practise. This is similar to the goal of SADFace to cover those
same concepts from a document-oriented structured graph, perspective. This contrasts with the goals
of AIF, for example, which seeks to be a comprehensive upper ontology of argumentative concepts,
an approach that can bring additional complexity and reduce clarity for end-users. One additional
application that we are investigating is the use of SADN when providing structured argumentative
information to Large Language Models (LLMs) [
There are a number of directions for future work. Firstly, refining the user experience of the SADN notation by implementing more syntactic sugar and shortcuts to make input and manipulation simpler and faster for experienced users. Secondly, improving the user experience within the SADFace REPL by using suggested auto-complete data from existing variables and elements within the current model. Thirdly, providing additional queues within the REPL using colour to diferentiate, i.e. keywords from variables and elements. Fourthly, extending the notation to support construction of dialogues along with the necessary machinery to link arguments with their associated dialogical elements.
In conclusion, SADN enables us to eficiently build an argument description, declaratively, interactively, and incrementally, in an eficient manner using a notation built upon the existing SADFace argument description model.
Partly supported by the Engineering and Physical Sciences Research Council (EPSRC) of the UK Government (grant number UKRI220).
The authors wish to thank the reviewers for the kind, interested, and useful suggestions which will inform the future directions of this work.