Start vocabulary file

2 files changed, 118 insertions, 0 deletions

diff --git a/README.md b/README.md
index 5fb1458..30fc423 100644
--- a/README.md
+++ b/README.md
@@ -28,3 +28,15 @@ For a property:
 - Domain (e.g. in "A loves B", A probably has to be a person, or at least some
   living being)
 - Range (e.g. in "A lives at B", B has to be a Location/Place)
+
+The file `VOCABULARY.md` contains these 2 lists. Other files such as `ISSUE.md`
+have plans and ideas and info, based on which the vocabulary is gradually
+written.
+
+The intention is to reuse properties and classes in the RDFiverse and
+ActivityPub! Some things in VOCABULARY.md may be removed in favor of existing
+entities defined in such places. As a result, though, we need to provide
+guidelines for the stuff that should be included in JSON-LD data sent between
+servers! For example, if we reuse `dc:author` from the Dublin Core ontology,
+eventually `ISSUE.md` should have an example for a JSON-LD issue object, to
+show the use of `dc:author` there.
diff --git a/VOCABULARY.md b/VOCABULARY.md
new file mode 100644
index 0000000..097363e
--- /dev/null
+++ b/VOCABULARY.md
@@ -0,0 +1,106 @@
+# Classes
+
+## IssueTracker
+
+An entity that can have a list of issues attached to it. It can be a
+repository, or a project, anything that can have its own list of issues. Note
+that while in repo hosting platforms issue are often attached to repos, this is
+*not* always the case, and it doesn't have to be this way (for example projects
+can use issue trackers where an issue can be associated with any number of
+repos). This class abstracts that concept of something that gets a list of
+issues attached.
+
+Superclasses: None
+
+## Issue
+
+Superclasses: None
+
+## User
+
+Right now let's say it's someone or something that can do actions, in
+particular open an issue. So it can be a real person, or it can be a bot. But
+it probably shouldn't be a group. It's an individual, either real human or
+automated software.
+
+Superclasses: ActivityPub Actor?
+
+# Properties
+
+## next-issue-number
+
+An issue tracker assigns numeric IDs to issues attached to it when they're
+created. Issue IDs could also be UUIDs and things like that, in which case this
+property is irrelevant of course.
+
+Superproperties: None
+
+Domain: IssueTracker
+
+Range: Positive integer
+
+## tracker
+
+The issue tracker to which an issue belongs.
+
+Superproperties: None
+
+Domain: Issue
+
+Range: IssueTracker
+
+## issue-number
+
+The numeric ID assigned to an issue by the tracker.
+
+Superproperties: None
+
+Domain: Issue
+
+Range: Positive integer
+
+## author
+
+The user who created a given issue. However note that issues may be edited, so
+this is NOT necessarily the user who's responsible for the current content of
+the issue! It's just who *initially* created it. Maybe change "author" to
+"creator" to be precise?
+
+Superproperties: None
+
+Domain: Issue
+
+Range: User
+
+## title
+
+One-line description of an issue.
+
+Superproperties: None
+
+Domain: Issue
+
+Range: Unicode text (one line though, i.e. no newlines)
+
+## description
+
+Detailed description of an issue.
+
+Superproperties: None
+
+Domain: Issue
+
+Range: Media tagged text? I mean, one option is Markdown. Another is HTML with
+some specific tags allowed. Another is text with a media type i.e. it can be
+various content types, and whoever displays the issue on a computer screen
+figures out the rendering details.
+
+## creation-time
+
+The time at which an issue was created.
+
+Superproperties: None
+
+Domain: Issue
+
+Range: UTC time? Attach timezone to it?