EPPJ
Erasmus-Project Prayer Journal
Specification: 15-Sep-2024
Last update: 16-Apr-2025
This document describes the Erasmus-Project Prayer Journal (EPPJ) specification. EPPJ is a way to specify and update online prayer requests. The goal of this specification is to define a way that decoupled EPPJ servers and EPPJ clients can interact with each other. The point of this specification is to provide a way for a client app to obtain prayer requests from multiple sources and present them to facilitate regular prayer for various organizations and individuals.
The goal of the specification is to provide a standard that can be used by anyone to communicate prayer needs through the internet. The use of this standard should provide a means of quickly and inexpensively updating prayer needs. With a simple EPPJ client, anyone can get updates to people and ministries that they support without having to manually check or request updated prayer cards. The goal is not to replace normal communication between ministers and prayer supporters, but to provide an alternative to the printed prayer cards that are used by those who pray regularly. To support these goals, the following philosophy is used:
o Open (non-proprietary) standard for the most widespread possible use. The lack of licensing fees or hidden feature sets means that anyone can implement the standard with minimal costs.
o Simplicity of use and implementation to reduce costs and encourage adoption as widely as possible. This involves a very simple file format and guidelines for easily dealing with formatting issues, which maximizes the chances of successful use by non-technical people.
o Provide for personal use as well as use by missionaries, churches, and other organizations.
o Require no special technology for serving up prayer lists other than the ability to place a text file on a web site for delivery through standard HTTP: or HTTPS: protocols. At the same time, keep server load at a minimum.
o Remain solely a data format/delivery standard. It is the client's responsibility to present prayer requests to users in a way that is appropriate to the client.
o Provide for prayer list security.
o Maintain backwards compatibility so that updates to the standard do not break older clients or served data.
The following terms are used in the specification:
Client. Any software used to retrieve a EPPJ file and display it to the user.
Directory. A collection of lists.
EPPJ File. A file containing data that follows this specification.
Prayer Item. A single prayer request within a prayer list.
Prayer List. A list of one or more related prayer items.
Server. An online web server that provides items to anyone who requests it.
The specific features addressed by the specification are as follows:
In order to define items in such a way that non-technical people can set up a server without too much trouble, yet provide easy-to-parse data for client apps, the specification uses a simple XML-like structure with the emphasis on being simple.
It is inevitable that over time, the specification will evolve. However, it is important to make it backwards compatible in such as way that future additions to the specification do not break older clients. This will be accomplished through the addition of new features - not the changing of old features. Clients should be able to safely ignore any new tags without a loss of previously-existing functionality. Thus, there is no need for a version identifier within the data itself.
We shall henceforth refer to the collection of data that a server provides as a "file", which contains tags for the benefit of any client that requests the file. The default URI for these files is "eppj.txt". The client must be provided with a URL that it can query for this file. For example, if "https://somedomain.com" is the URL provided to the client, the client will attempt to download the "https://somedomain.com/eppj.txt" file for processing.
The client must gracefully handle a missing file, taking into consideration that the file could be momentarily missing in the process of being updated or due to temporary internet outages. Of course, it is also possible that the URL provided to the client may simply not be a URL that serves up the file. The client must also honor any redirects and, if so, not contact the URL again automatically (such as on restart of the app).
The organization responsible for maintaining an EPPJ server must first construct their eppj.txt file, place it on their server, and then give out the URL that can be used by EPPJ clients.
With some programming on the server, a prayer list can be secured. This is accomplished by the server responding to a request for the eppj.txt file with the word "secure" (no HTML tags). The client will handle this response by prompting the user for a password. A second request with the requested password is then sent by the client with the URI format:
eppj.txt?pwd=X
where "X" is the password. The client should save the password for subsequent requests to check for updates, but the saved passwords should be kept secure. Note that a request with an invalid password or no password sent to a secured server should result in a repeat response of "secure" (without the quotes).
To provide for future enhancements with backwards compatibility, the client should compare only the first six characters of the response, ignoring anything thereafter.
An EPPJ file consists of a series of tags, where each tag starts with "<" and ends with ">". Most tags consist of a pair of matching tags, although there are a couple exceptions to this. The start and end tags are identical with the exception that the end tag contains a slash after the "<". For example, here is a tag pair:
<startdate>10/24/2025</startdate>
Each tag should be lowercase, but the client should not assume this. Upon encountering a tag the client doesn't recognize, it must skip to the matching end tag - thus ignoring them. This provides backward compatibility for newer tags added to the specification later, and also ignores tags which are in error. There is no way for the client to know if it is a new tag or an error tag.
It is possible that an EPPJ editor app could be developed to help users construct files without errors, however that is beyond the scope of this specification.
There are three types of file, determined by their intended use:
These three types of files cannot be mixed together in a single file. Each has separate valid tags. However, all EPPJ files must begin with the following tag which has no ending tag:
<eppj>
This indicates that the file is an EPPJ server file. If this is not the first text found in the file, the client should assume it is not an EPPJ file. How the client responds to the lack of the tag is up to the implementation, but should most often be handled as if the file isn't on the server at all. This addresses the situation that there might be an eppj.txt file on existent servers that are not EPPJ servers.
Note that a closing </eppj> tag is allowed at the end of the file, but is not required, and it may be ignored by the client, which means that any tags following that may still be processed by the client.
In most cases, a redirection is not necessary. In many cases a directory file is not required. So, the Prayer file will be the main focus of most organizations providing EPPJ servers.
There are two types of redirection files: hard redirects and load-balancing. Hard redirects are used to redirect the client to an EPPJ file in another location. In other words, the file has been moved. The client should take note of this and not reference the original URL again. Soft redirects are used for load-balancing. The intention is that large organizations may wish to spread out the load among many servers if they expect many client requests.
Note that neither type of redirection may be nested. That is, you cannot redirect to an EPPJ file that then redirects. This avoids infinite circular redirects and makes the client simpler.
Format: <redirect>URL</redirect>
where URL is the URL to redirect to. Example:
https://newserver.com
There should be no other tags after this because the client will immediately redirect after encountering this and will do no further processing of the file.
Format: <balance>pURL</balance>
where URL is a URL that provides an EPPJ file. "p" is optional and can be used to define the percentage chance of redirecting to that URL. The format of the "p" field is "n%:" where "n" is a numeric value indicating the percentage chance of redirection to this item. The client must process all balance tags and then choose between them appropriately. Tags without a percentage field are all treated as equally likely. If there is a mix of tags with and without percentages, the client must add up the percentage of the tags with percentages and then divide the remainder of 100% between all tags without percentages. Example:
<balance>10%:https://prayerserver1.com</balance>
<balance>20%:https://prayerserver2.com</balance>
<balance>30%:https://prayerserver3.com</balance>
<balance>https://prayerserver4.com</balance>
<balance>https://prayerserver5.com</balance>
<balance>https://prayerserver6.com</balance>
Note that if the percentage adds up to more than 100%, it is entirely reasonable that the client may not pick any URLs that come after reaching 100%. Do not forget both the percent sign (%) and colon (:) if you specify the percentage. Also, it is expected that each URL contains the same exact EPPJ file, or else the client may behave in an unexpected manner since the client may check again and end up at a different server. If one of the servers is not available, the client must try again, excluding that server from the list of possibilities.
Directory files provide a collection of named prayer lists, allowing a user to choose which prayer lists they wish to subscribe to. If there is only one list, a directory file is not only unnecessary, but an extra burden on the server and a possible confusion to the end user. For each list in the directory, there should be the following structure:
<dir>
<name>NAME</name>
<file>URL</file>
</dir>
where "NAME" is description of the list and "URL" is either a relative or absolute URL of an EPPJ file containing the corresponding prayer list. For example:
<dir>
<name>US Supreme Court</name>
<url>prayers/ussc</url>
</dir>
<dir>
<name>First Baptist Church</name>
<url>https://firstbaptist.org</url>
</dir>
This provides two prayer lists. The target file must be an EPPJ Prayer file (described in the following section). If a file is specified without a domain, its name will be appended to the URL of the directory file.
Prayer List files contain one or more prayer requests. Each individual prayer request is called an "item". An item starts with an <item> tag, and should end with a </item> tag. If the client encounters another <item> tag before the </item> of the previous item, the client will treat it as an implied </item> tag followed by a new item.
Some tags delimit text intended for the end user. These tags will be marked with "Textual tag" in the following. This text is assumed to be HTML, so any less than signs (<) or ampersands (&) must use the < and & entities. Clients are not assumed to be able to process HTML other than the following tags:
<br>
<i>
<b>
<u>
In addition, the following optional non-HTML tags can be used:
<bcv=X></bcv>
<bc=X><bc>
These tags are used to mark text as being a bible book or verse reference. the bcv tag pair indicates a book/chapter/verse reference and the bc tag pair indicates a whole book/chapter reference, where "X" is the reference. Examples:
<bcv=John 3:16>ver. 16</bcv>
<bc=Genesis 1>Gen. 1</bc>
These tags are not expected to have any affect on the appearance of the text in the clint - although the client may alter the text appearance if desired. The intention is to present the client with optional information about the text contents.
The text may also use the < entity to include the less-than sign (<) in the text.
If a client cannot display HTML, it should replace "<br>" with new line, replace "<" with "<", and extract the other tags before displaying it as plain text. No other HTML tags or entities should be used, and will be ignored by the client if encountered.
Format: <id>TEXT</id>
where "TEXT" is a unique label for this item. This is required in order for the client to track the same item over time even when the prayer text changes or the status changes to "answered". This id text can contain any text except less than signs (<). the choice of text is up to the author, though probably the best approach is to simply use a one-up number. For instance, the first item created would be "1", the second would be "2", and so forth. Note that the id only needs to be unique within a Prayer List file - it doesn't apply across different files.
Format: <title>TEXT</title>
where "TEXT" is the text of a title or heading for this item. Note that this is optional and it is up to the client whether or not, and how, this is displayed to the user. This is always interpreted as plain text.
Textual tag
Format: <text>CONTENTS</text>
where "CONTENTS" is the text of this item.
Example:
<text>Pray that the <b>Carapana</b> people come to know Jesus.</text>
Format: <more>URL</more>
where "URL" is a URL specification. This indicates a link to a web page that provides more information. This is optional and should be displayed in the client as "Read more" or something similar. If the url doesn't start with "http://" or "https://", the url is prefixed with "https://". Example:
<
Format: <
where "URL" is the URL specification of the image. This is optional and, if present, there can only be one image per item. Display by the client is optional. Ideally, this should be a JPG file, but PNG and BMP should be supported by EPPJ clients. Note that GIF or video is not supported.
Textual tag
Format: <answered>TEXT</answered>
where "TEXT" indicates that the prayer item was answered.
Format: <startdate>DATE</startdate>
where "DATE" is a date specification of one of the following formats:
YEAR/MM/DD
MM/DD/YEAR
DAY
where "YEAR" is a 4-digit year value (such as "2024"), "MM" is a 1 or 2 digit month value (from 1 to 12), "DD" is a 1 or 2 digit day value (1-31), and "DAY" is a day-of-the-week (0=Sunday, 1=Monday, ..., 7=Saturday). If a month, day, or month/day combination is invalid, the client will ignore this tag. Note that the year must be 4 digits so that the client can determine which format is used. Example:
<startdate>12/25/2025</startdate>
Wildcards are allowed in the year field to indicate the current year. Example:
12/25/*
Likewise, a day specification serves as a wildcard meaning that day in the current week (eg, every Wednesday). Any form of wildcard implies both a start and end date for a single day. Normally, the client can discard any items whose end date is prior to the current date, but the presence of a wildcard indicates that the item will merely be hidden until the date becomes current again.
The purpose of this tag is to indicate when the item will begin to show to the user. If the tag is not supplied, the item is ready to be shown immediately. The presence of a wildcard allows a recurring prayer request for a specific start day in the year.
Format: <enddate>DATE</enddate>
where "DATE" is a date specification of one of the following formats:
YEAR/MM/DD
MM/DD/YEAR
where "YEAR" is a 4-digit year value (such as "2024"), "MM" is a 1 or 2 digit month value (from 1 to 12), and "DD" is a 1 or 2 digit day value (1-31). If a month, day, or month/day combination is invalid, the client will ignore this tag. Note that the year must be 4 digits so that the client can determine which format is used. Example:
<enddate>11/30/2025</enddate>
Wildcards are not allowed in this tag.
The purpose of this tag is to indicate when the item will stop showing to the user. If the tag is not supplied, the item will be shown indefinitely. The specified date is the last date that the item can show. Thereafter, the item should be hidden.
startdate and enddate tags are used together to solicit prayer for events of limited duration. The lack of both indicates a prayer request that will show consistently until the user requests the client to hide it. enddates should not be used for answered prayers; rather the answered tag should be used.
Format: <set>TEXT</sub>
where "TEXT" is some arbitrary text that identifies a set of prayer requests. The text, however, cannot contain any less-than signs (<). Example:
<set>1</set>
The purpose of this tag is to have the client iterate through a collection of items. All items with the same set specification are considered members of the same set. For sets of exactly 7 items, a startdate tag with a day wildcard for each will result in a more consistent display across clients. For each set, the client will iterate through the items in the set, displaying one each day. The contents of the text can be anything but should not include less than signs (<).
Textual tag
Format: <urgent>TEXT<urgent>
where "TEXT" describes the urgency. Example:
<urgent>Health emergency - prayer needed ASAP</urgent>
This tag pair is intended to indicate an urgent prayer need. It is up to the client as to how to display this, but it should be in a way that makes the item stand out among the other items.
Format: <url>WEBURL</url>
where "WEBURL" is a URL specification. Unlike the other tags, this one applies to the entire list rather than a specific item. There should only be one in a Prayer List file, and if there are multiple instances, the client can choose whichever one it desires. This differs from the <more> tag in that <url> applies to the whole list and <more> applies to a specific item. Example:
<url>https://Mysite.com</url>
The point of this tag is to allow a user to read more about the organization or the prayer list. The tag is optional and the handling of it is up to the client.
16-Apr-2025
Added <bcv>, </bcv>, <bc>, and </bc> tags to specification.
Added < entity to specification.