This guide is for the newer version of the PeriodO client hosted at https://client.perio.do/. If you are using the older version of the PeriodO client hosted at https://test.perio.do/, see the old guide.
Open and browse the canonical periods
The PeriodO client runs in your browser. You can use it to browse or edit any dataset that conforms to the PeriodO data model. But most people are probably interested in looking at the canonical dataset of periods curated by the PeriodO project.
When you first open the client, you are prompted to select an existing data source or specify the location of a new data source. The client supports loading data from three kinds of sources:
A web source is a URL (web address starting with
http). Data loaded from the web (including the canonical dataset) can only be browsed, not directly edited.
A file source is a local JSON file. Data loaded from files are also browse-only.
An in-browser source is a database running in your browser. Data from an in-browser source can be edited as well as browsed.
Initially you should see only one data source: the canonical PeriodO dataset (at
Clicking on the name of the data source (Canonical) will load its data into the client, and you should see an interface for browsing it:
At the bottom you will see a scrollable list of periods. Initially, this list will include all of the periods in the dataset. The periods in the list can be sorted by clicking on the column headers. Hovering over a period in the list will display, below the list, detailed information about the selected period and the authority that defined it. Clicking on a period to select it will keep the detailed view focused on it. You can use the up and down arrow keys to change the selected period.
Navigate to a period
The rows in the period list are numbered. Click a row’s number to navigate to that period.
Navigating to an individual period will show some key points about it: preferred label, temporal extent, and spatial coverage, all as given by the source authority, to which a Defined by link is provided. Any notes from the original author or the editors who added the period are shown here too.
Every period in the canonical dataset has been assigned a stable, permanent URL, also known as a Permalink. Right-click on this link to copy it. You should always use the permalink when referring to a period or sharing it with others—URLs displayed in the browser address bar may change over time, but permalinks are (relatively) guaranteed to be resolvable for the long term.
To Download the period as structured data (JSON or Turtle), click on the appropriate link.
Navigate to an authority
When viewing a period, click the name of the authority that defined the period (after Defined by) or click on Authority > View in the navigation menu to navigate to the authority.
Navigating to an individual authority will show its name, creators, and other citable information. Any notes from the original author or the editors who added the authority are shown here too, if they are relevant to the authority as a whole.
As with periods, every authority in the canonical dataset also has been assigned a Permalink. Again, you should always use the permalink when referring to an authority or sharing it with others.
To Download the authority as structured data (JSON or Turtle), click on the appropriate link.
Find and compare periods
After opening a dataset you can get back to the dataset browsing interface by clicking Dataset > Browse in the navigation menu.
You can search for periods by label, and you can find sets of periods defined by specific authorities, having preferred labels in specific languages, or having specific spatial coverage.
To search for periods by label, enter some text in the search box. If the Labels option is selected, the search will be restricted to the preferred (original) label of each period. If the Labels + alternate labels option is selected, the search will also include the alternate (translated) labels of each period.
To filter for periods defined by specific authorities, locate the desired authorities in the Authority list: these are listed in descending order by the number of periods they contain (indicated to the left of the authority’s name). You can use
Ctrl+F to search for an authority by name.
Clicking on an authority filters the list of periods to include only periods belonging to that authority, and moves the selected authority to the top of the Authority list. Selecting multiple authorities will show all the periods defined by those authorities. Clicking Clear at the top of the authority list will show all the periods again.
Filtering by language works just like filtering by source: click on one or more languages in the Language list to show only periods with preferred labels in those languages.
The spatial coverage of a period in PeriodO can be specified in two ways: 1) as a string of text (usually a place name, but sometimes a description of multiple places) quoted from the source authority, and 2) as a set of links to places identified in Wikidata. As a result there are two ways to filter periods by spatial coverage.
The first way to filter periods by spatial coverage uses the descriptions quoted from the source authorities, and works just like filtering by language or authority. Locate the desired spatial coverage description in the Spatial coverage list, and select it by clicking. Again, you can use
Ctrl+F to search for a specific place name in a spatial coverage description.
The second way to filter periods by spatial coverage uses the links to Wikidata places. Under Filter by place, click Select places. A map and a search box will appear.
Enter some text to see a list of matching place names. Select a place name to add it to the filter. Adding multiple places to the filter will show periods linked to any of those places. The spatial coverage of the places in the filter will be shown on the map, until you click Done. To remove a place from the filter, click the X following the place name, or use
Tab to highlight the place name and then press
Searches and filters can be combined; for example you might search for periods that 1) have
bronz in their labels, 2) are linked with the Wikidata records for Spain or France, and 3) are defined by the ARIADNE authority. The resulting list will include only periods that satisfy all three of these criteria.
The periods satisfying the current search and filter criteria are visualized as spans on a timeline and as regions on a map.
Use the timeline to compare the temporal extents of the selected periods. There are two styles of timeline. The histogram style shows, for each unit of time, how many of the selected periods include that unit. The stacked bars style shows the temporal extent of each period as a horizontal bar.
Use the map to get a sense of the combined spatial coverage of the selected periods, as specified by the Wikidata places they are linked to. The regions highlighted in purple indicate the spatial extents of all the Wikidata places linked to by the selected set of periods. If you focus on a period by clicking on or hovering over it in the tabular list of periods, the the spatial extents of the Wikidata places linked with that one period will be highlighted in red.
The map display should be interpreted cautiously, as not all periods are linked to Wikidata places, and not all Wikidata places are currently mappable (meaning we do not yet have an authoritative source for the geometry of their spatial extents—learn more about the PeriodO place name gazetteers.)
Get periods as structured data (JSON or Turtle)
The canonical PeriodO dataset can be downloaded as a JSON-LD file:
Or as a Turtle file:
Create or edit your own periods
To edit or create new periods and authorities, you must create a local, in-browser database. To do this, first navigate to Home > Data sources. Under Add data source, set the Type to In-browser (editable), give your data source a label and (optionally) a description, and click Add.
You should see your newly added data source appear in the list of data sources. Click the name of your data source to open it.
Initially your data source will be empty. Before you can add any periods, you first need to create an authority or source for the definition of the period. Every period belongs to an authority, even if it was informally published. Navigate to Data source > Add authority to create a new authority.
First you need to provide some citable information about the authoritative source—information that could be used to find it online or in a library. If the source is a book or some other kind of artifact held by a library anywhere in the world, you can easily provide this information by looking it up in the WorldCat catalog. Search for the item in WorldCat, and navigate to the item’s catalog page. Copy the Permalink in the upper right-hand corner, and paste it into the Linked data box in the PeriodO interface. Then click the ⟳ button to load citable information directly from WorldCat.
If the source is a scholarly article or other artifact that has been assigned a digital object identifier or DOI, you can also copy and paste the DOI into the Linked Data box to load citable information directly from the CrossRef database.
If the source is something less formally published, such as a web page, you’ll need to enter citable information manually. Click the Not linked data tab to do this. Try to enter as much descriptive information as possible.
If the source is a page-numbered text, and all of the periods that it defines are on a single page (for example in a table), you can also put that page number in the Locator field (whether or not you manually entered the other citable information). If the periods defined by the authority are on different pages, don’t put that information here—put it with the description of each period.
If there is anything to else important to note about the authority that isn’t specific to one of the periods it defines, put it in the Editorial notes.
Press Save to create your new authority. You will be navigated to Authority > View and should see your new authority with no periods in it.
To add a period to the empty authority, navigate to Authority > Add period.
Under Original label, give the name of the period as it is given in the authoritative source. If the original label is in English, you needn’t provide any Alternate labels unless alternate names are given in the source. If the original label is not in English, you should add at least one alternate label in English. You can specify the language for each label, and if the language is one with multiple written scripts, you should specify the script as well.
If the period is defined at a particular location in the authoritative source—for example a specific page or figure in a text—put that information in the Locator field. If the authoritative source is a website, and period is defined on a particular page in that website, put the URL of that page in the URL field.
Periods are commonly arranged into hierarchies. You can create hierarchies when adding or editing a period either by referencing a broader period that the currenrt one is Part of, or by listing narrower periods that the current one contains (Has parts). (You need not do both; indicating a relationship pointing from broader to narrower will also establish a relationship from narrower to broader, and vice versa.) Note that hierarchies can only contain periods from the same authority, so it is only possible to add broader or narrower links once you have added at least one other period to an authority.
Periods are often defined as modifications of periods defined by others. PeriodO records these relationships as Derived from links. Unlike broader and narower relations, derivation relations can (and usually should) relate periods from different authorities. To add derivation relations to periods from a different authority, that authority needs to be included in your editable data source.
To remove any referenced period, click the X beside its name.
The Spatial coverage of a period can be described in two complementary ways. Under Description, give the spatial coverage as it is described in the source. This description should be taken verbatim from the text of source, in whatever form it may appear: table header, figure caption, etc. If there is absolutely no mention in the source of a spatial region to which the period is relevant, you can leave the description blank.
Under Coverage area, you can select (from placename gazetteers) specific places that correspond to the description you entered. Even if there is no mention in the source of a spatial region to which the period is relevant, you still should be able to infer such a region from what you know about the source: select places that correspond to this inferred region. The places you have selected will appear as a list of gray boxes labeled with place names. To remove a place from the list, click the X on the box. If you cannot find a place you would like to add to the coverage area, please contact us and we’ll add it to our placename gazetteers.
To describe the Temporal coverage of a period, first look at how it is described in the source. Typically, periods will be defined as extending from some (possibly vague) Start time to some (possibly vague) Stop time. For example, a source might defined a period as extending from “1000 BCE” to “500 BCE”, or from the “end of the 1st century AD” to the “start of the 5th century”. In such cases, you would enter each part of the description—taken verbatim from the source—as the Label for the start and stop, respectively.
After you have entered a label for the start or stop of the period, the interface will attempt to automatically translate what you’ve entered into a range of standardized year values. For example, a label of “1000 BCE” would be translated to the standardized year
-0999, while a label of “start of the 5th century” would be translated to the range of standardized years from
Depending on what the label is, the interface may not be able to translate it into a standardized form. In that case, uncheck the Parse dates automatically box and enter the standardized forms yourself. If either the start or the stop of the period is a range of dates—expressing some uncertainty or vagueness about when it started or stopped—check the Two part date box to enter that range.
In some cases a source will describe the temporal coverage of a period using a single phrase, rather than separately describing the start and the stop. In a case like this, enter the description as the label for the start, but leave the label for the stop blank. Then turn off automatic date parsing, and fill in the standardized values for the start and the stop. For example a period described as covering the “last quarter of the twentieth century” would correspond to a range from starting in
1975 and stopping in
1999, even though the textual description does not explicitly distinguish these two endpoints.
Finally, you can add explanatory notes about the period. The Note field is for explanatory text taken directly from the source. The Editorial note field is for explaining decisions that the author of the PeriodO record (that’s you!) made. For example, explanations of judgment calls about alternate labels, spatial coverage, or temporal coverage could go here.
Click the Save button to finish adding your new period. You will be navigated to the authority view, which should now list your single new period.
Editing existing periods
Rather than creating your own periods and authorities from scratch, you may want to edit periods from the canonical dataset or from a file that someone shared with you. Or you may want to derive new periods from canonical ones.
To work from a file, you first need to add the file as a (read-only) data source. Navigate to Home > Data sources and under Add data source set the type to File. Give your data source a name, click Choose File, and select the file with the dataset you wish to load. Click Add and your new data source will be created.
Now you will import into your editable, in-browser database the periods you want to edit or from which you want to derive new periods. (See how to create an editable database.) Navigate to Data source > Import changes. Select from which of the Available data sources you would like to import data. If you created a new data source from a file, or if you created other in-browser data sources, you should see them listed here; otherwise you can import changes from the canonical dataset.
After you’ve made your selection, you will see a list of the differences or “changes” between the data source you’re currently editing and the data source from which you want to import data. If the data source you’re editing is empty, these changes will look like a list of new authorities.
Select the changes you would like to add to the data source you’re editing, scroll down to the bottom, and click Continue. You will see a summary with only the changes you selected. Click Accept changes to confirm, and the changes will be applied. Now you can edit any period by first browsing to it and then navigating to Period > Edit. If you add a new period to this data source, you will be able to refer to the imported periods as sources from which the new period is derived.
Contribute to the canonical periods
Anyone can submit new periods or corrections to existing periods to be considered for inclusion in the canonical dataset. To do this, first either create or edit some periods. Then, navigate to Data source > Submit changes.
You will be prompted to select a web-based data source to submit your changes to. Typically this will be the canonical data source. After you’ve made your selection, you will see a Log in with your ORCID link.
An ORCID is a unique code for identifying scholarly authors and contributors. It is free to register for an ORCID. Click the login link to enter your ORCID and ORCID account password, or to register for a new ORCID account. PeriodO will never see your ORCID account password: you are logging into
orcid.org, which then provides a temporary token allowing us to authenticate you.
After successfully logging into the ORCID site, you should see the message Currently signed in as followed by whatever name you have registered with ORCID.
Click Continue to see a list of the differences or “changes” between the data source that contains your new or corrected periods and the data source to which you want to submit them.
Select the changes you would like to submit, scroll down to the bottom, and click Continue. You will see a summary with only the changes you selected. Click Submit changes to confirm, and you should see the message Submitted changes. Thanks for your contribution! We will take a look at it ASAP and may contact you with questions.
To check on the status of your submission, navigate to Home > Data sources and select the web data source to which you submitted your changes (again, typically this will be the canonical data source). Then navigate to Data source > Review submitted changes to see a list of all the submissions that have been made. Your new submission should be on top (unless someone else submitted changes in the meantime). Each submission shows the date and time it was made, who made it, and its status: Open means no decision has been made, Merged means the changes were accepted, and Rejected means the changes were rejected.
Click on a submission’s status to see any comments that have been made about the submission, or to download the submitted changes as JSON. (You will also see controls to accept or reject the changes, but unless you are authorized to make changes to the web data source to which the changes were submitted, your acceptance or rejection will fail.)